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 project or codebase SHOULD be descriptive and free from acronyms, abbreviations, puns or branding for names.
- Any code, documentation and tests MAY have a translation.
Why this is important
- Make your codebase and what it does understandable for a wider variety of stakeholders in multiple contexts.
- Helps with the discoverability of your codebase.
What this does not do
- Make explanations of your codebase’s functionality understandable
- Make your organization’s jargon understandable without an explanation
How to test
- See if 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
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 documentations and descriptions in proposals and changes, if you can’t understand something, probably others will also not
Developers and designers: what you need to do
- Frequently test with other policy makers and management in the process if they understand what you are delivering and how you document it