Use plain English

Requirements

All codebase documentation MUST be in English.

Examples

• Notify documentation

All source 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.

This applies to everything that is in a “released” state. During development, lag may occur.

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.

While you should try to keep the language plain, don’t be afraid to create a glossary for terms that are specific for the domain and would cause even more confusion if they were not used.

Documentation SHOULD aim for a lower secondary education reading level, as recommended by the Web Content Accessibility Guidelines 2.

Resources

• Understanding Reading Level of the WCAG with resources for evaluating the reading level of a text

Tools

• LanguageTool - spelling and grammar
• Grammarly - grammar
• Hemingway text editor - readability
• Upgoer 5 text editor by Theo Sanderson, only allows 1000 most common words

Providing a translation of any code, documentation or tests is OPTIONAL.