Documentation and reproducibility

Why documentation matters

• Projects become difficult to understand without documentation
• Documentation is essential from a reproducibility perspective
• Properly organised documentation encourages reuse

Good documentation should

• Explain what the project is about
• Link together data, code and environment
• Record how the analyses were performed
• Provide clear instructions for reproducibility
• Happen continuously throughout the project
• Describe how to discuss the project

The README file

The README.md file is the most important piece of documentation and should answer the following questions:

1. What is this project about?
2. Is there a publication related to this project?
3. What is contained in this repository?
4. What is the minimum hardware requirements to reproduce the analyses?
5. How do I reproduce the analyses?
6. What outputs should I expect?
7. How can a reader discuss with the author?

Questions?