In researching what developers wanted to learn about writing documentation for users, the most common issue related to how much, or how little, they should write. One developer said:
“I would want to know what is the minimum I should write. If you can persuade me what is the necessity of each thing I’m capturing, and the voice I should use to make it most acceptable, I think I’d tune in.”
We’ll look at this question in the Writing Skills for Developers course, which we will be releasing soon. In general, you need to:
- Meet the legal requirements (which differ depending on the product, and the country).
- Provide enough information so that users don’t give up using your product, if they get stuck. For example, how to install the software, and how to get started.
- Consider the support calls, and whether you could avoid any of those by having good user documentation.
That might appear a bit too vague, so let me go back to one of the sentences above:
“If you can persuade me what is the necessity of each thing I’m capturing”
Before you start writing, you should define the purpose and audience for each deliverable you create. There should be a use case:
- Without documentation, is it clear what the user should be doing? is it clear what the user should be doing first?
- Is it clear how they should be doing the task?
- When they have to choose between options, do they have enough information to make the right decision?
- When they have completed a task, do they know what to do next?
- Are there any concepts or terms the user might not understand?
You can assess what topics to cover by doing some basic usability analysis. However, if you think about the tasks, the process (workflow), and any unfamiliar concepts, you will be on the right track.