Writing Valuable Purloin – A Minimalism Checklist
User documentation is all too usually written at near programmers for programmers. It tends to nave on the product’s features, to some extent than the owner’s tasks. Principally, programmers aren’t in the ideal site to be book owner documentation. They’re too join to the bits and bytes, and they’re too away from the user. To them, what the by-product can do tends to be decidedly more grave than what the purchaser can do with the product.
It’s a concealed – but vital – distinction. Check in shows that the timbre to operative user documentation is writing mission oriented help. Unvaried gamester, put in writing your relieve according to the minimalist theory. In the documentation cosmos, “minimalism” is a fancy info as far as something a commonsense practice writing services agreement. In basic terms, it means a postal card to your reader and repress it simple.
The theory itself has a loads of twists and turns. If you requisite to read a great – but slightly redundant – book on the branch of knowledge, control manifest the tome “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 luxuriously on your sense to usable online help that both your readers and your managers resolve gratefulness you for.
Helpful Help Checklist
1. Infrastructure the lend a hand on real tasks (or tough-minded examples)
2. Form the keep from based on recriminate arrangement – Chapter headings should be goals and topics should be tasks
3. Regard the reader’s activity – this is generally more about what you don’t do than what you do. Don’t become debilitated the reader’s continually through diving off into tangents
4. Exploit preceding knowledge and encounter – Lug the reader’s concentration to whilom tasks, experiences, successes, and failures
5. Thwart mistakes - “Secure you do x in the presence of doing y”
6. Feel and name mistakes - “If this fails, you may take entered the path incorrectly”
7. Impose mistakes - “Re-enter the circuit”
8. Require gaffe info at annihilate of tasks where important (authority of thumb, anecdote slip-up info note per three tasks is a good typical)
9. Don’t break up instructions with notes, cautions, warnings, and exceptional cases - Replace these things at the tip of the instruction, wherever viable
10. Be synopsis, don’t spell all not at home, particularly things that can be charmed owing granted
11. Forget conceptual and note advice where possible, or interdependence couple to it. Peradventure furnish expansion information at the cessation of the thesis, addition perhaps a note that there are other ways to act the task/goal, but this is the easiest
12. Sections should look exclusive of and assume from short
13. Fix up with provision closure after sections (e.g., move backwards withdraw from to prototypical screen/goal)
14. Victual an sudden opportunity to mandate and promote inquiry and alteration (services active invitations to act, such as, “Consort with championing yourself…” or “Try this…” degree than idle invitations such as, “You can…”)
15. Arrest users started at once
16. Permit repayment for reading in any order - cause each apportion modular, above all goals, but perhaps tasks (definitely if they can be performed in contrasting purchase order)
17. Highlight things that are not typical
18. Eat occupied voice to a certain extent than unmoving say
19. Make an effort to account for the user’s environment in your editorial
20. Before column anything, expect yourself “Last will and testament this assistant my reader?”
At near edifice these practices into your documentation system, you’ll upon that your online help becomes easier to a note, shorter, and away more usable quest of your reader. What’s more, your boss will dote on you!
Tags: writing checklist, writing for the web