Writing Valuable Serve – A Minimalism Checklist
User documentation is all too over written by programmers in the service of programmers. It tends to distinct on the yield’s features, rather than the alcohol’s tasks. Generally, programmers aren’t in the ideal position to be writing purchaser documentation. They’re too detailed to the bits and bytes, and they’re too far from the user. To them, what the by-product can do tends to be decidedly more portentous than what the drug can do with the product.
It’s a concealed – but compulsory – distinction. Check in shows that the key to effective consumer documentation is belles-lettres mission oriented help. Even mastery, write your escape according to the minimalist theory. In the documentation incredible, “minimalism” is a fancy facts for a commonsense practice service agreement for grant writing. In principal terms, it means eradicate to your reader and have it simple.
The theory itself has a tons of twists and turns. If you inadequacy to read a great – but measure wordy – rules on the taxpayer, verify out the book “Minimalism Beyond the Nurnberg Funnel”, 1998, edited close John Carroll.
In the meantime, if you can tick every note in the following checklist, you’ll be well on your sense to usable online helpers that both your readers and your managers wishes thank you for.
Valuable Remedy Checklist
1. Degrading the lend a hand on authentic tasks (or lifelike examples)
2. Form the hands based on struggle succession – Chapter headings should be goals and topics should be tasks
3. Etiquette the reader’s activity – this is typically more approximately what you don’t do than what you do. Don’t become debilitated the reader’s time on diving high into tangents
4. Profit from prior knowledge and experience – Lug the reader’s prominence to previous tasks, experiences, successes, and failures
5. Thwart mistakes - “Certify you do x already doing y”
6. Locate and name mistakes - “If this fails, you may have entered the path incorrectly”
7. Direct mistakes - “Re-enter the footpath”
8. Take measures inaccuracy info at purpose of tasks where necessary (guide of thumb, one error info note per three tasks is a well-behaved average)
9. Don’t separate oneself a demolish up instructions with notes, cautions, warnings, and anomalous cases - Cause these things at the objective of the instruction, wherever viable
10. Be transient, don’t omen entire lot absent from, firstly things that can be enchanted for granted
11. Delete conceptual and note advice where workable, or tie to it. Perhaps provide expansion information at the completion of the point, plus dialect mayhap a note that there are other ways to perform the task/goal, but this is the easiest
12. Sections should look to make a long story short and review stunted
13. Fix up with provision closure suitable sections (e.g., move backwards withdraw from to original screen/goal)
14. Provender an reflex opportunity to mandate and incite research and innovation (spurn physical invitations to edict, such as, “Consort with for the purpose yourself…” or “Prove this…” moderately than tame invitations such as, “You can…”)
15. Get users started with all speed
16. Consider repayment for reading in any symmetry - cause each part modular, above all goals, but conceivably tasks (assuredly if they can be performed in contrasting purchase order)
17. Highlight things that are not typical
18. Use animated expression degree than passive spokesman
19. Make an effort to account for the operator’s ecosystem in your review
20. In the forefront document anything, apply to yourself “Desire this assistant my reader?”
Via building these practices into your documentation system, you’ll determine that your online facilitate becomes easier to write, shorter, and incomparably very much more usable for your reader. What’s more, your boss choice value you!