A starter style guide
Basic tips for writing useful documentation
Summary
For a general audience, the tone and content of documentation should be simple, inclusive, and supportive.
Make it simple
- Use short sentences
- Write in the present tense
- Explain words that are necessary but unfamiliar
- Use concrete nouns and verbs, not metaphors or idioms
- Ruthlessly remove words that are interesting but unnecessary
Don’t write
Your licence for this content will expire at the end of a 5-year period.
Do write
You can use this image for the next 5 years.
Make it inclusive
- Use everyday words
- Be device agnostic
- Consider the age and accessibility needs of your audience
- Avoid cultural idioms and any language relating to gender, race, religion, or sexuality
Don’t write
users, click, tap, move the cursor, computer, see the table below
Do write
you, choose, use, select, device, use the information in the table
Make it supportive
- Focus on the reader’s objective
- Make it easy for the reader to scan your content
- Sound like a polite and knowledgeable human, not an impersonal system
Don’t write
jo.asti@gmail.com has already been invited to your organization. A reminder email has been sent to the user.
Do write
We’ve sent an invitation to HenryK3@gmail.com.