Use Appropriate Language
Use the appropriate language for your organization. For example, if your organization uses English as its standard language, use English. Multinational organizations typically standardize on English.
Use Correct Grammar
Use Correct Grammar! Use a grammatically correct form of the language in all documentation. This is critical nowadays where teams are often made up of individuals from various countries whose first language isn’t always the language used by the organization.
Don’t Use Slang
Never use slang (for example, ‘did ya get me?’).Never use text message forms of words (for example “u” instead of “you”).
Be respectful of others. Not everyone understands all slang and many people do not understand short-cut words used in texting.
Abbreviations
Make sure any abbreviations, acronyms and symbols you use in documentation are clear. For each abbreviation, acronym, and symbol you use, make sure you:
- Include a description or spell it out the first time you use it
- Include a glossary or table to explain it.
Using Numbers and Units
Make sure all numbers specify the relevant units (for example, 5L, 16cm, 13mg), except for unitless constants such as Pi etc.
The units are part of the description of the number so be sure to include (common abbreviations are acceptable; e.g., mg).
Again, be cognizant of “localization” – measurements in inches –v- metric units, weights in ounces –v- milligrams, degrees F –v- C, etc. Without specifying the units, confusion may arise.
