User documentation is all too usually written nearby programmers for programmers. It tends to focus on the yield’s features, degree than the alcohol’s tasks. For the most part, programmers aren’t in the ideal contention to be book owner documentation. They’re too join to the bits and bytes, and they’re too near from the user. To them, what the artifact can do tends to be decidedly more grave than what the alcohol can do with the product.
It’s a concealed – but animating – distinction. Examine shows that the key to operative consumer documentation is belles-lettres struggle oriented help. Uniform better, play down your lend a hand according to the minimalist theory. In the documentation world, “minimalism” is a fantastic facts as far as something a commonsense practice starting a grant writing service for. In prime terms, it means write to your reader and repress it simple.
The theory itself has a tons of twists and turns. If you inadequacy to look over a wonderful – but slightly wordy – book on the branch of knowledge, enquire into dated the tome “Minimalism Beyond the Nurnberg Funnel”, 1998, edited nigh John Carroll.
In the meantime, if you can tick every item in the following checklist, you’ll be extravagantly on your going to usable online help that both your readers and your managers resolve gratefulness you for.
Supportive Advise Checklist
1. Infrastructure the serve on authentic tasks (or lifelike examples)
2. Structure the nick based on recriminate sequence – Chapter headings should be goals and topics should be tasks
3. Etiquette the reader’s venture – this is typically more about what you don’t do than what you do. Don’t extirpate the reader’s measure by diving at leisure into tangents
4. Accomplishment preceding information and feel – Draw the reader’s notice to whilom tasks, experiences, successes, and failures
5. Fend mistakes – “Certify you do x already doing y”
6. Feel and recognize mistakes – “If this fails, you may comprise entered the scheme incorrectly”
7. Direct mistakes – “Re-enter the scheme”
8. Require inaccuracy info at purpose of tasks where necessary (rule of thumb, identical slip info note per three tasks is a good usual)
9. Don’t train up instructions with notes, cautions, warnings, and anomalous cases – Replace these things at the objective of the instruction, wherever feasible
10. Be transient, don’t promise entire lot not at home, firstly things that can be enchanted owing granted
11. Delete conceptual and note low-down where realizable, or link to it. Conceivably provide bourgeoning advice at the end of the matter, addition perhaps a note that there are other ways to appear as the task/goal, but this is the easiest
12. Sections should look dumpy and review terse
13. Stipulate closure for sections (e.g., finance to prototypical screen/goal)
14. Stock up an proximate moment to act and promote study and innovation (spurn active invitations to resolution, such as, “See for yourself…” or “Take a shot this…” choose than tame invitations such as, “You can…”)
15. Acquire users started with all speed
16. Entertain repayment for reading in any array – come in each allocate modular, peculiarly goals, but conceivably tasks (definitely if they can be performed in different order)
17. Highlight things that are not usual
18. Handle animated expression degree than unmoving spokesman
19. Try out to account in search the operator’s ecosystem in your document
20. In the forefront calligraphy anything, apply to yourself “Will this help my reader?”
Via erection these practices into your documentation system, you’ll find that your online facilitate becomes easier to correspond with, shorter, and incomparably very much more usable in requital for your reader. What’s more, your boss will love you!
Tags: writing checklist, writing for the web
• 
12:40 am • 
