Documenting data¶

What should you document ?¶

You should document the data so that people can understand it - what units data is is, how 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.

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