Standard for Public Code

目次

  1. Requirements
  2. Why this is important
  3. What this does not do
  4. How to test
  5. Policy makers: what you need to do
  6. Management: what you need to do
  7. Developers and designers: what you need to do
  8. Further reading

到 GitHub 貢獻

Use plain English

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.
  • The name of the codebase SHOULD be descriptive and free from acronyms, abbreviations, puns or organizational branding.
  • 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.

Why this is important

  • Makes the codebase and what it does understandable for a wider variety of stakeholders in multiple contexts.
  • Helps with the discoverability of the codebase.
  • Can help you meet the European Union accessibility directive, which requires most public sector information to be accessible.

What this does not do

  • Make explanations of the codebase’s functionality understandable.
  • Make your organization’s jargon understandable without an explanation.

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.

Policy makers: what you need to do

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

Management: 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 management 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