Standard for Public Code
← Document the code Use open standards →

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

Use plain English

English is the de facto language of collaboration in software development.

Public sector information needs to be accessible to all its constituents. Plain and simple language makes the codebase and what it does easier to understand for a wider variety of people.

Translations further increase the possible reach of a codebase. Language that is easy to understand lowers the cost of creating and maintaining translations.

Requirements

  • All codebase documentation MUST be in English.
  • All code MUST be in English, except where policy is machine interpreted as code.
  • All bundled policy not available in English MUST have an accompanying summary in English.
  • Any translation MUST be up to date with the English version and vice versa.
  • There SHOULD be no acronyms, abbreviations, puns or legal/non-English/domain specific terms in the codebase without an explanation preceding it or a link to an explanation.
  • Documentation SHOULD aim for a lower secondary education reading level, as recommended by the Web Content Accessibility Guidelines 2.
  • Providing a translation of any code, documentation or tests is OPTIONAL.

How to test

  • Confirm that codebase documentation is available in English.
  • Confirm that source code is in English, or confirm any non-English is policy or terms with preceding explanations.
  • Confirm any non-English policy has an accompanying summary in English.
  • Confirm that translations and the English version have the same content.
  • Check that no unexplained acronyms, abbreviations, puns or legal/non-English/domain specific terms are in the documentation.
  • Check the spelling, grammar and readability of the documentation.

Public policy makers: what you need to do

  • Frequently test with other managers, developers and designers in the process if they understand what you are delivering and how you document it.

Managers: what you need to do

  • Try to limit the use of acronyms, abbreviations, puns or legal/non-English/domain specific terms in internal communications in and between teams and stakeholders. Add any such terms to a glossary and link to it from the places they are being used.
  • Be critical of documentation and descriptions in proposals and changes. If you don’t understand something, others will probably also struggle with it.

Developers and designers: what you need to do

  • Frequently test with policy makers and managers if they understand what you are delivering and how you document it.
  • Ask someone outside of your context if they understand the content (for example, a developer working on a different codebase).

Further reading