Principle 6 Document Your Work

Maintain documentation for your code. Code is not self documenting and code without documentation won't be useful later. You need to capture higher level context such as what the code is for, why it is written a certain way and what the inputs and outputs are.

You Must - Produce documentation in line with Aqua book guidance.

You Should - Assemble documentation as you code.

You Could - Use document generation tools to produce documentation.

Related Areas: Reproducibility
Comments

6.1 Aqua Book Guidance for Technical Documentation:

Pages 42-43 of the Aqua book contains guidance on documentation that should be in place as part of a quality assurance process for any analysis. The scope of the Aqua book is wider than code, however the definition of technical documentation is useful and repeated here:

All analysis should have documentation for the user, even if that 'user' is just the analyst leading the analysis.

This is to ensure that they have captured sufficient material to assist them if the analysis is revisited in due course. For analysis that is more likely to be revisited or updated in the future, documentation should be provided to assist a future analyst and should be more comprehensive.

This documentation should include:

  • a summary of the analysis including the context to the question being asked,
  • what analytical methods were considered,
  • what analysis was planned and why,
  • what challenges were encountered and how they were overcome
  • and what verification and validation steps were performed.

In addition, guidance on what should be considered if the analysis is to be revisited or updated is beneficial.

6.2 Document as you Go

Don't fall into the trap of assuming documentation is something which is produced at the end. The best time to put together the documentation is as you are planning or doing the work - while it is fresh in your mind. This also means that switching projects wont result in undocumented work.

6.3 Use a Documentation Generator

There are popular tools for generating documentation from your code and comments. These lighten the load of producing and publishing good documentation, and encourage you to produce thorough documentation.

There are many documentation generators. Doxygen or Roxygen are recommended.

6.4 README.md

It is good practice to include a README.md document within your repository.

README files typically include information on:

  • What the code does
  • Why the code is useful
  • How users can get started with the code
  • Where users can get help with your code
  • Who maintains and contributes to the code

Put the README file in your repository's root (i.e. the top level folder which contains/is the repository). This makes it easy to find. It also means that when you view your repository on github (or other git repository hosting sites), that it will be rendered nicely and prominently displayed.

You can view the README for the repository which produces this book here: README.md

See About READMEs for more.