Document the code

General

Tools

• Docusaurus
• Read the docs
• mkdocs
• readme.so is a tool to create a README file

Resources

• How to write a README, guide from the municipality of Amsterdam.

Requirements

All of the functionality of the codebase, policy as well as source code, MUST be described in language clearly understandable for those that understand the purpose of the code.

Examples

The documentation of the codebase MUST contain a description of how to install and run the software.

Examples

The documentation of the codebase MUST contain examples demonstrating the key functionality.

Examples

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.

Examples

• CKAN: “CKAN is an open-source DMS (data management system) for powering data hubs and data portals. CKAN makes it easy to publish, share and use data. It powers hundreds of data portals worldwide.”
• OpenFisca description

The documentation of the codebase SHOULD contain a section describing how to install and run a standalone version of the source code, including, if necessary, a test dataset.

Examples

The documentation of the codebase SHOULD contain examples for all functionality.

Examples

The documentation SHOULD describe the key components or modules of the codebase and their relationships, for example as a high level architectural diagram.

Examples

• DigiTransit UI architecture

There SHOULD be continuous integration tests for the quality of the documentation.

Including examples that make users want to immediately start using the codebase in the documentation of the codebase is OPTIONAL.

Examples

• CKAN showcase implementations