Include a glossary of technical terms used in the product documentation.
High-quality material that is clear, concise, and consistent.
Poor-quality material that causes confusion and misunderstanding.
If your competitors have products of equal capability that are easier to use, your customers will desert you.
- Use consistent terminology throughout the material.
- In your glossary of technical terms, provide examples to go along with the term definitions.
- Avoid jargon
- Avoid idioms, slang, and too much “cuteness.”
This is a good rule for both technical and marketing material. However, a certain level of “cuteness” is what often makes marketing material, especially advertising, effective.
- Follow a policy of “one concept, one word.”
- Keep sentences short and simple.
Dependent clauses cause particular problems for non-native English speakers.
- Use active voice whenever possible.
- Use a simple vocabulary and conventional syntax.
- Use bullets to break up longer thoughts.
- Avoid colors that are difficult to read (e.g. red and green).
- Use graphics whenever “a picture will equal a thousand words.” However, take care to avoid appearing “junky.”
- Use a modular design that “chunks” material in sections of no more than a few paragraphs each.
- Avoid icons that are not immediately obvious (and don’t assume that what’s obvious to use is obvious to other people).