- Not too much detail
- Good title
- Engage your reader
- Clear instructions
- Q&A format
- Additional material
I. General recommendations
Write to a level of detail that is appropriate to your audience → most of the times you are writing for a general, non-technical audience! Therefore, do not go into too much technical detail and make sure you define all important terms and jargon.
Pick a good title – it’s how the reader will know if this document truly answers their questions or not.
Include a summary of the topics covered in the document. To avoid repeating yourself, try using the following:
• “We’ll show you …”
• “We’ll explain …”
• “Learn how …”
• “This page …”
Make your writing engaging
• When appropriate, use humour and emotion
• Try avoiding the use of the passive voice. You can use a conversational writing style – an active style similar to the way you’d speak to someone
• Try to express the same content in different ways, as we all have different learning styles
• Repetition will help people remember what you’ve explained
• User images and video whenever necessary
Make step-by-step instructions, easy to follow
• Pick the most user-friendly way
• Include expected results when giving instructions
Usually a Question & Answer (Q&A) format works well. For this, think of the questions you would come up with when facing that particular feature – if you have questions about it, most likely your readers will too. Make sure though, the answers are simple and concise so that the reader doesn’t get lost.
If necessary, add links to related articles/documents.
Avoid the use of large-screen captures