Readability/Voice/Tone:
- Be as clear and simple as possible. Avoid technical terminology/jargon for communications to non-technical audiences.
- Keep headlines and paragraphs short and scannable. Users often scan to find the most relevant or important information.
- Use second person and describe actions to a user. Consider that technical content talks to users when support agents can’t.
- When addressing users, use “you” but when the audience is developers or system administrators, use “participant” to refer to end users, and “you” to address the technical employees.
- Do not use first person (don’t say We recommend…instead say, For best results, the image should be cropped).
- Use active voice (The system resets automatically). Avoid passive voice (The support team reset the systemis preferable to The system was reset by the support team).
- Don’t say things like, “Click here” or “Read this.” Instead, link relevant keywords (Visit the IT Services page for more information).
- Clearly explain situations and how they can be resolved (Password must contain upper and lowercase letters. Try again.). Do not use overly dramatic words for simple errors (bad request, forbidden, fatal, invalid).
- Look for ways to help users solve problems automatically (Did you mean “gmail.com?”). Do not use error numbers or codes unless easily recognizable by the audience.
- Use lists for steps, groups, or sets of information. Include a brief introduction to the list. Number lists only for step-by-step instructions.
- Tone does not have to be strictly informal or formal. Either way, it should be professional and straightforward.
- Don’t use all uppercase letters for emphasis. Italics and bold may be used sparingly for emphasis.
Examples of Good/Bad Writing:
Don’t say this:
The fatal error was cleared by the support team. We suggest users CLICK HERE in order to review the error report for the 404 error.
Instead, say:
The support team cleared the error. Review the error report.