Document the code
- All of the functionality of the codebase – policy as well as source – MUST be described in language clearly understandable for those that understand the purpose of the code.
- The documentation of the codebase MUST contain:
- a description of how to install and run the source code,
- examples demonstrating the key functionality.
- The documentation of the codebase SHOULD contain:
- a high level description that is clearly understandable for a wide audience of stakeholders, like the general public and journalists,
- a section describing how to install and run a standalone version of the source code, including, if necessary, a test dataset,
- examples for all functionality.
- There SHOULD be continuous integration tests for the quality of your documentation.
- The documentation of the codebase MAY contain examples that make users want to immediately start using the codebase.
- You MAY use the examples in your documentation to test the code.
Why this is important
- Users can start using and contributing more quickly.
- You help people discover the codebase, especially people asking ‘is there already code that does something like this’.
- This provides transparency into your organization and processes.
What this does not do
- Contribute directly to more reusable, portable code (see Create reusable and portable code).
How to test
- Other stakeholders, professionals from other public organizations and the general public find the documentation clear and understandable.
- Documentation is generated from code.
- Links and images are automatically tested.
Policy makers: what you need to do
- Check in regularly to understand how the non-policy code in the codebase has changed.
- Give feedback on how to make non-policy documentation more clear.
Management: what you need to do
- Try to use the codebase.
- Make sure you understand both the policy and source code as well as the documentation.
Developers and designers: what you need to do
- Check in regularly to understand how the non-source code in the codebase has changed.
- Give feedback on how to make non-source documentation more clear.
- Documentation guide by Write the Docs.