Writing Helpful Help A Minimalism Checklist

Writing Helpful Help A Minimalism Checklist

User documentation is​ all too often written by programmers for programmers. it​ tends to​ focus on​ the​ product’s features,​ rather than the​ user’s tasks. Generally,​ programmers aren’t in​ the​ ideal position to​ be writing user documentation. They’re too close to​ the​ bits and bytes,​ and they’re too far from the​ user. to​ them,​ what the​ product can do tends to​ be far more important than what the​ user can do with the​ product.

It’s a​ subtle – but vital – distinction. Research shows that the​ key to​ effective user documentation is​ writing task oriented help. Even better,​ write your help according to​ the​ minimalist theory. in​ the​ 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​ the​ subject,​ check out the​ book “Minimalism Beyond the​ Nurnberg Funnel”,​ 1998,​ edited by John Carroll.

In the​ meantime,​ if​ you can tick every item in​ the​ 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 the​ help on​ real tasks (or realistic examples)

2. Structure the​ help based on​ task sequence – Chapter headings should be goals and topics should be tasks

3. Respect the​ reader's activity – this is​ generally more about what you don’t do than what you do. Don’t waste the​ reader’s time by diving off into tangents

4. Exploit prior knowledge and experience – Draw the​ 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 the​ path incorrectly"

7. Fix mistakes - "Re-enter the​ path"

8. Provide error info at​ end of​ tasks where necessary (rule of​ thumb,​ one error info note per three tasks is​ a​ good average)

9. Don't break up instructions with notes,​ cautions,​ warnings,​ and exceptional cases - Put these things at​ the​ end of​ the​ instruction,​ wherever possible

10. Be brief,​ don't spell everything out,​ especially things that can be taken for granted

11. Omit conceptual and note information where possible,​ or​ link to​ it. Perhaps provide expansion information at​ the​ end of​ the​ topic,​ plus maybe a​ note that there are other ways to​ perform the​ task/goal,​ but this is​ the​ easiest

12. Sections should look short and read short

13. Provide closure for sections (e.g.,​ back to​ original screen/goal)

14. Provide an​ immediate opportunity to​ act and encourage exploration and innovation (use active invitations to​ act,​ such as,​ "See for yourself..." or​ "Try this..." rather than passive invitations such as,​ "You can...")

15. Get users started quickly

16. Allow for reading in​ any order - make each section modular,​ especially goals,​ but perhaps tasks (definitely if​ they can be performed in​ different order)

17. Highlight things that are not typical

18. Use active voice rather than passive voice

19. Try to​ account for the​ user's environment in​ your writing

20. Before writing anything,​ ask yourself “Will this help my reader?”

By building these practices into your documentation process,​ you’ll find that your online help becomes easier to​ write,​ shorter,​ and far more usable for your reader. What’s more,​ your boss will love you!

Related Posts:

Powered by Blogger.