Documentation and reproducibility
16-Jan-2026
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:
- What is this project about?
- Is there a publication related to this project?
- What is contained in this repository?
- What is the minimum hardware requirements to reproduce the analyses?
- How do I reproduce the analyses?
- What outputs should I expect?
- How can a reader discuss with the author?
