Source: Documentation. The Turing Way Community. This illustration is created by Scriberia with The Turing Way community, used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807.
Why writing documentation is important?
For you:
- You will be using your code in 6 months.
- You want people to use your code and give you credit.
- You want to learn self-determination.
- Others would be encouraged to contribute to your code.
For others:
- Others can easily use your code and build upon it.
For science:
- Allow reproducibility and transparency.
What should you document about your research?
Everything! All the data, notes, code, and materials someone else would need to reproduce your work.
Versions
- Your code project should be versioned (version control).
- Enable reproducibility and avoid confusion: documentation should be versioned as well.
- Have you ever seen: “We will soon release a new version and are updating the documentation. Some features may not be available in the version you have downloaded.”?
Documentation should be placed and tracked close to the source code
- Documenting close to the source code (e.g. subdirectory doc/) minimizes barrier to contribute.
- I should not need to log in to another machine or service and jump through hoops to contribute.
- It is often good enough to have a README.md or README.rst along with your code/script.
Use a standard markup language
- Offers formatting flexibility, enforces a basic document structure and the rendered documents can be exported to other formats (e.g. for printing). Also, the source can be read by humans without knowledge of the language in case the rendered document is unavailable.
- CodeRefinery suggests using either reStructuredText (RST) or Markdown markup.
- GitHub and GitLab automatically render README.md or README.rst files.
Copy-paste-able
- PDF alone is not enough since copy-pasting out of a PDF document can be difficult.
- It is OK to provide a generated PDF in addition to a copy-paste-able format.
Written by humans
- Automatically generated documentation (e.g. API documentation) is useful as complementary documentation but it does not replace tutorials written by humans.
Installation instructions
- Give step by step instructions for the basic case. Additional information and caveats can be linked from there.
- List requirements and dependencies (libraries, compilers, environment).
- Include instructions for how to test for correctness after installation.
Make the license explicit
- Without a license, your work is under exclusive copyright by default: others are not allowed to re-use or modify anything.
- GitHub and GitLab allows to choose a license from common license templates.
Information for contributors
- Make it easy for others to contribute: document how you prefer others to contribute.
- Users of your code may be shy to contribute code. Your documentation provides a platform for your first contributions.
Writing good README files
The README file (often README.md or README.rst) is usually the first thing users/collaborators see when visiting your GitHub repository.
Use it to communicate important information about your project! For many smaller or mid-size projects, this is enough documentation. It’s not that hard to make a basic one, and it’s easy to expand as needed.
GitHub automatically generates a table of contents for README.md files.
Sources:
How to document your research software (CodeRefinery). https://coderefinery.github.io/documentation/wishlist/
How to Write Good Documentation (UC Berkeley Library). https://guides.lib.berkeley.edu/how-to-write-good-documentation
Last updated: 21/02/2024
