Standard for Public Code

Contents

  1. Requirements
  2. How to test
  3. Public policy makers: what you need to do
  4. Managers: what you need to do
  5. Developers and designers: what you need to do
  6. Further reading

Contribute on GitHub

Document the code

Well documented source code helps people to understand what the source code does and how to use it. Documentation is essential for people to start using the codebase. It also makes contributing to the codebase easier.

Requirements

  • All functionality MUST be described in a clear language. The audience is those that understand the purpose of the codebase.
  • The documentation MUST contain a description of how to install and run the software.
  • The documentation MUST contain examples demonstrating the key functionality.
  • The documentation SHOULD contain an overview that is easy to understand by a wide audience. The audience includes the general public and journalists.
  • The documentation SHOULD contain a section describing how to install and run a standalone version of the software. This includes a test dataset if necessary.
  • The documentation SHOULD contain examples for all functionality.
  • The documentation SHOULD describe the key components or modules and their relationships. For example, this could be done as a high level architectural diagram.
  • There SHOULD be continuous integration tests for the quality of the documentation.

How to test

  • Confirm that other stakeholders find the documentation clear and understandable. Stakeholders should include professionals from other public organizations and the general public.
  • Confirm that the documentation describes how to install and run the source code.
  • Confirm that the documentation includes examples of the key functionality.
  • Check with members of the general public and journalists if they can understand the overview.
  • Check that the instructions for how to install and run a standalone version of the source code result in a running system.
  • Check that all functionality documented contains an example.
  • Check that the documentation includes a high level architectural diagram or similar.
  • Check that documentation quality is part of integration testing. For example, test that documentation is generated correctly, and test links and images.

Public 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.

Managers: what you need to do

  • Try to use the codebase so that you can provide feedback. This can improve how the policy and source code are documented. For example, is the documentation good enough to persuade a manager at another public organization to use this 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