Voice and Tone¶
How you speak and write are usually different. You may speak in long sentences and use colloquial phrases. Traditional technical writing is formal and could be considered dry. The documentation should be clear, accurate, and direct, but also casual.
Write your documents with the user’s needs and expectations in mind. Imagine that you are helping a professional acquaintance.
The target audience includes people who belong to different cultures. Remember that some forms of expressions that are normal for one culture are insulting for another. Sound professional, attentive, and emotionally neutral.
Rules¶
- Write in a friendly, conversational, and respectful tone but don’t be frivolous. Do not use a playful tone.
- Focus on facts, real user tasks, and real user benefits. Avoid promotional hype at all costs.
- Write in the second person and, where appropriate, in an imperative mood (e.g. “Do this”.)
-
Write in the present tense. Keep sentences short.
-
Use active voice where possible. Passive voice is acceptable when any of these conditions is true:
- The system performs the action.
- It is more appropriate to focus on the receiver of the action.
- You want to avoid blaming the user for an error, such as in an error message.
- The information is clearer in passive voice.
- Introduce abbreviations before using them. At the first occurrence in the document, an abbreviation should contain the expanded version in parentheses.
- Do not write that something is easy or simple.
- Do not use subjective attributes such as simple, efficient, and so on in combination with the feature that you are describing. Subjective attributes are permissible if you intend to demonstrate these characteristics.
- Remove modal verbs (must, may, could, should, etc.) if they do not add to the meaning of the sentence.
Last update:
June 26, 2023
Created: June 26, 2023
Created: June 26, 2023