Standard for Public Code

Document your code

Requirements

  • All of the functionality of your 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 your codebase MUST contain the following:
    • a description of how to install and run the source code
    • a selection of examples, demonstrating the key functionality
  • The documentation of your codebase SHOULD contain the following:
    • a high level description that is clearly understandable for a wide audience of stakeholders such as 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 your codebase MAY contain the following:
    • examples that make users want to immediately start using your codebase!
  • You MAY use the examples in your documentation to test your code

Why this is important

  • Users can start using and contributing more quickly
  • You help people discover your codebase, especially people asking ‘is there already code that does something like this’
  • Provide transparency into your organization and processes

What this does not do

  • Contribute directly to more reusable, portable code (see Coding in the open)

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

  • Try to periodically understand what the non-policy code in the codebase does
  • 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 as well as its documentation

Developers and designers: what you need to do

  • Try to periodically understand what the non-source code in the codebase does

Further reading