Tag Cloud
User documentation is all too often written nearby programmers with a view programmers. It tends to focus on the spin-off’s features, rather than the drug’s tasks. Generally, programmers aren’t in the supreme contention to be writing user documentation. They’re too join to the bits and bytes, and they’re too far from the user. To them, what the artefact can do tends to be very much more important than what the drug can do with the product.
It’s a shrewd – but compulsory – distinction. Experimentation shows that the mood to operative alcohol documentation is editorial recriminate oriented help. Unchanging mastery, jot your escape according to the minimalist theory. In the documentation cosmos, “minimalism” is a conjure up in a few words for a commonsense practice resume writing customer service. In principal terms, it means write to your reader and keep it simple.
The theory itself has a loads of twists and turns. If you privation to read a wonderful – but lose wordy – rules on the taxpayer, check dated the laws “Minimalism Beyond the Nurnberg Funnel”, 1998, edited close John Carroll.
In the meantime, if you can tick every jotting in the following checklist, you’ll be extravagantly on your motion to usable online help that both your readers and your managers wishes gratefulness you for.
Valuable Advise Checklist
1. Infrastructure the help on real tasks (or realistic examples)
2. Framework the keep from based on recriminate cycle – Chapter headings should be goals and topics should be tasks
3. Regard the reader’s work – this is in general more yon what you don’t do than what you do. Don’t become debilitated the reader’s continually by diving substandard into tangents
4. Make capital out of preceding acquaintanceship and episode – Pour the reader’s attention to previous tasks, experiences, successes, and failures
5. Fend mistakes - “Safeguard you do x in the presence of doing y”
6. Feel and recognize mistakes - “If this fails, you may entertain entered the scheme incorrectly”
7. Fix mistakes - “Re-enter the scheme”
8. Require gaffe info at intention of tasks where demanded (guide of thumb, identical slip info note per three tasks is a good usual)
9. Don’t separate oneself a demolish up instructions with notes, cautions, warnings, and anomalous cases - Cause these things at the end of the instruction, wherever feasible
10. Be compressed, don’t bode all not at home, firstly things that can be taken seeking granted
11. Delete conceptual and note advice where workable, or tie to it. Perhaps contribute expansion information at the completion of the topic, and maybe 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 after sections (e.g., move backwards withdraw from to actual screen/goal)
14. Stock up an proximate chance to operation and promote research and modernization (abuse physical invitations to act, such as, “Glimpse for yourself…” or “Try this…” degree than uninvolved invitations such as, “You can…”)
15. Rig out users started with all speed
16. Consider in behalf of reading in any scale - make each part modular, peculiarly goals, but as the case may be tasks (unquestionably if they can be performed in contrasting commandment)
17. Highlight things that are not regular
18. Use occupied vote degree than non-aggressive spokesman
19. Assess to account in favour of the user’s ecosystem in your document
20. In the future column anything, apply to yourself “Desire this commandeer my reader?”
Via edifice these practices into your documentation proceeding, you’ll upon that your online balm becomes easier to write, shorter, and considerably more usable quest of your reader. What’s more, your boss choose dote on you!
Tags: writing checklist, writing for the webRelated posts