Use plain English
- All code and documentation MUST be 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/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 branding.
- Documentation SHOULD aim for a lower secondary education reading level, as recommended by the Web Content Accessibility Guidelines 2.
- Any code, documentation and tests MAY have a translation.
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
- Check that translations and the English version have the same content.
- Validate that no unexplained acronyms, abbreviations, puns or legal/domain specific terms are in the documentation.
- Test the documentation for grammar using Grammarly.
- Test the documentation for readability using Hemingway text editor.
- Ask someone outside of your context if they understand your content (for example, a developer working on a different codebase).
Policy makers: what you need to do
- Frequently test with other management, designers and developers 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/domain specific terms in internal communications in and between teams and stakeholders.
- 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.
- Text of the Web Content Accessibilty Guidelines 2.1, Guideline 3.1 Readable - make text content readable and understandable.
- Upgoer 5 text editor - only allows 1000 most common words.