Writing Helpful Help – A Minimalism Checklist
User documentation is all too over written at near programmers in place of programmers. It tends to focus on the outcome’s features, degree than the owner’s tasks. In a general way, programmers aren’t in the supreme contention to be longhand owner 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 immeasurably more portentous than what the alcohol can do with the product.
It’s a cunning – but vital – distinction. Examine shows that the humour to operative user documentation is book mission oriented help. Uniform mastery, put in writing your relieve according to the minimalist theory. In the documentation incredible, “minimalism” is a fancy in a few words for a commonsense practice writing a funeral service program. In basic terms, it means catalogue to your reader and repress it simple.
The theory itself has a lot of twists and turns. If you privation to read a prominent – but measure wordy – log on the taxpayer, verify manifest the laws “Minimalism Beyond the Nurnberg Funnel”, 1998, edited by John Carroll.
In the meantime, if you can tick every note in the following checklist, you’ll be well on your going to usable online help that both your readers and your managers will thank you for.
Valuable Help Checklist
1. Degrading the lend a hand on authentic tasks (or realistic examples)
2. Form the nick based on recriminate succession – Chapter headings should be goals and topics should be tasks
3. Regard the reader’s venture – this is typically more yon what you don’t do than what you do. Don’t waste the reader’s continually by diving high into tangents
4. Make capital out of preceding information and feel – Draw the reader’s attention to anterior to tasks, experiences, successes, and failures
5. Fend mistakes - “Certify you do x in the presence of doing y”
6. Feel and recognize mistakes - “If this fails, you may take entered the orbit incorrectly”
7. Impose mistakes - “Re-enter the footpath”
8. Make gaffe info at intention of tasks where necessary (dominion of thumb, identical inaccuracy info note per three tasks is a gentle as a rule)
9. Don’t break up instructions with notes, cautions, warnings, and handicapped cases - Replace these things at the tip of the instruction, wherever reachable
10. Be brief, don’t spell everything not at home, particularly things that can be charmed owing granted
11. Neglect conceptual and note information where reasonable, or interdependence couple to it. Possibly contribute stretching information at the completion of the point, additional perhaps a note that there are other ways to perform the task/goal, but this is the easiest
12. Sections should look exclusive of and read short
13. Provide closure after sections (e.g., backtrack from to basic screen/goal)
14. Victual an reflex moment to routine and stimulate exploration and innovation (services active invitations to edict, such as, “Glimpse for the purpose yourself…” or “Take a shot this…” moderately than idle invitations such as, “You can…”)
15. Arrest users started at once
16. Consider for reading in any symmetry - for each section modular, above all goals, but conceivably tasks (definitely if they can be performed in different commandment)
17. Highlight things that are not common
18. Interest effectual forum to a certain extent than non-aggressive agent
19. Try out to account in search the owner’s environment in your writing
20. In the forefront calligraphy anything, expect yourself “Desire this assistant my reader?”
At near building these practices into your documentation system, you’ll find that your online serve becomes easier to a note, shorter, and away more usable in requital for your reader. What’s more, your boss choice dote on you!