Documenting data » History » Version 4
Version 3 (Steve Welburn, 2012-08-22 02:47 PM) → Version 4/7 (Steve Welburn, 2012-08-22 02:48 PM)
h1. Documenting data
h2. What should you document ?
You should document the data so that people can understand it - what units the data is in, is, how the data was created, why the data was created and possible uses for the data.
As well as summary documentation for the entire dataset, individual data files should have their own documentation.
h2. How to document data
* Use a suitable directory structure. Individual data files can then have documentation giving a summary of the meaning of all files within a folder rather having individual pieces of documentation for each file
* Use meaningful filenames
** The more meaningful the better
** However, they should be succinct
** It may be necessary to refer to an explanation of the filenames to identify their content
** Files may be moved from their original directory structure so filenames should be sufficient to identify a particular file
* If documentation is required to understand file contents, copy the documentation when copying the files
* Use standard file formats where possible - and preferably open formats so that files can be reused
* Create README files with textual explanations of file content
* Use the capabilities of file formats for self-documentation
** If you have text files of data, consider including comment lines for explanations
** Fill in author, title, date and comments for file formats that support them
** Consider including <!-- --> comments in XML data
* If data is created algorithmically / by code
** Consider automatically writing out textual descriptions when the data is created
** Document the values of all the parameters used to create the data
** Remember to document the actual values of parameters for which default values were accepted - the default values may change with different versions of the code
h2. What should you document ?
You should document the data so that people can understand it - what units the data is in, is, how the data was created, why the data was created and possible uses for the data.
As well as summary documentation for the entire dataset, individual data files should have their own documentation.
h2. How to document data
* Use a suitable directory structure. Individual data files can then have documentation giving a summary of the meaning of all files within a folder rather having individual pieces of documentation for each file
* Use meaningful filenames
** The more meaningful the better
** However, they should be succinct
** It may be necessary to refer to an explanation of the filenames to identify their content
** Files may be moved from their original directory structure so filenames should be sufficient to identify a particular file
* If documentation is required to understand file contents, copy the documentation when copying the files
* Use standard file formats where possible - and preferably open formats so that files can be reused
* Create README files with textual explanations of file content
* Use the capabilities of file formats for self-documentation
** If you have text files of data, consider including comment lines for explanations
** Fill in author, title, date and comments for file formats that support them
** Consider including <!-- --> comments in XML data
* If data is created algorithmically / by code
** Consider automatically writing out textual descriptions when the data is created
** Document the values of all the parameters used to create the data
** Remember to document the actual values of parameters for which default values were accepted - the default values may change with different versions of the code