Standard for Public Code

Document the code

Requirements

  • 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

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.

Further reading