User documentation is all too often written by programmers for programmers. It tends to focus on
product’s features, rather than user’s tasks. Generally, programmers aren’t in ideal position to be writing user documentation. They’re too close to bits and bytes, and they’re too far from user. To them, what product can do tends to be far more important than what user can do with product. It’s a subtle – but vital – distinction. Research shows that key to effective user documentation is writing task oriented help. Even better, write your help according to minimalist theory. In documentation world, “minimalism” is a fancy word for a commonsense practice. In basic terms, it means write to your reader and keep it simple.
The theory itself has a lot of twists and turns. If you want to read a great – but slightly wordy – book on subject, check out book “Minimalism Beyond Nurnberg Funnel”, 1998, edited by John Carroll.
In meantime, if you can tick every item in following checklist, you’ll be well on your way to usable online help that both your readers and your managers will thank you for.
Helpful Help Checklist
1. Base help on real tasks (or realistic examples)
2. Structure help based on task sequence – Chapter headings should be goals and topics should be tasks
3. Respect reader's activity – this is generally more about what you don’t do than what you do. Don’t waste reader’s time by diving off into tangents
4. Exploit prior knowledge and experience – Draw reader’s attention to previous tasks, experiences, successes, and failures
5. Prevent mistakes - "Ensure you do x before doing y"
6. Detect and identify mistakes - "If this fails, you may have entered path incorrectly"
