You readers are trying to reach a destination. Make sure you write docs that help them get there.
Imagine if your GPS unit said, "Turn right, "turn left and then figure out the rest yourself."
How would you feel? Frustrated? Angry?
But that is exactly what most software documentation does. It leaves gaping goals that readers are somehow supposed to fill in themselves.
Killer Documentation doesn't leave out any steps at all.
You need to think like a GPS
Your readers have a place where they are at. They have a destination where they want to arrive. Your job is to be the GPS that gives them the step-by-step directions on how to get there. Watch the video below to learn a little more about this subject.
Document tasks, not features
First, don't talk about features in your documentation. Talk about tasks. Talking about features is like having your GPS unit tell you all about history of the city you are driving in. While that may be interesting, it isn't going to help you get anywhere.
Tasks are what your readers are trying to accomplish so don't beat around the bush. Just tell them every step they need to complete to accomplish the task.
How to make sure you cover all of the steps
The best way we have found to make sure you don't leave anything out is to never, ever, write from memory. Make sure that you are actually doing the task you are documenting. A really good approach is to use a tool like ScreenSteps or Clarify to capture each an image of each step of the task you are documenting. By taking a picture each step of the way you make sure that you don't leave anything out.
Another approach is to record a screencast of yourself accomplishing the task (though this can take a lot longer).
Add your comment