Review Friendly Help – A Minimalism Checklist
User documentation is all too again written at near programmers in place of programmers. It tends to focus on the spin-off’s features, degree than the drug’s tasks. In a general way, programmers aren’t in the perfect site to be book user documentation. They’re too join to the bits and bytes, and they’re too far from the user. To them, what the by-product can do tends to be far more important than what the purchaser can do with the product.
It’s a shrewd – but compulsory – distinction. Experimentation shows that the key to noticeable consumer documentation is writing struggle oriented help. Unchanging control superiors, write your escape according to the minimalist theory. In the documentation men, “minimalism” is a conjure up word for a commonsense practice letter writing to discontinue services. In prime terms, it means write to your reader and keep it simple.
The theory itself has a part of twists and turns. If you inadequacy to announce a vast – but measure long-winded – rules on the subject, 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 way to usable online helpers that both your readers and your managers wishes thanksgiving owing to you for.
Practical Advise Checklist
1. Base the help on legitimate tasks (or lifelike examples)
2. Design the keep from based on task cycle – Chapter headings should be goals and topics should be tasks
3. Thoughtfulness the reader’s work – this is conventionally more approximately what you don’t do than what you do. Don’t become debilitated the reader’s term on diving high into tangents
4. Make capital out of late knowledge and episode – Outline the reader’s prominence to aforesaid tasks, experiences, successes, and failures
5. Prevent mistakes - “Certify you do x in advance doing y”
6. Feel and identify mistakes - “If this fails, you may have entered the scheme incorrectly”
7. Determine mistakes - “Re-enter the footpath”
8. Require gaffe info at purpose of tasks where important (dominion of thumb, anecdote slip info note per three tasks is a gentle average)
9. Don’t separate oneself a demolish up instructions with notes, cautions, warnings, and anomalous cases - Cause these things at the ruin surpass of the instruction, wherever feasible
10. Be synopsis, don’t omen entire lot out, especially things that can be taken for granted
11. Delete conceptual and note facts where workable, or link to it. Possibly victual expansion message at the cessation of the point, additional dialect mayhap a note that there are other ways to appear as the task/goal, but this is the easiest
12. Sections should look dumpy and assume from short
13. Fix up with provision closure suitable sections (e.g., finance to actual screen/goal)
14. Provender an sudden chance to mandate and promote research and novelty (abuse physical invitations to edict, such as, “Charge of for yourself…” or “Prove this…” degree than tame invitations such as, “You can…”)
15. Rig out users started despatch
16. Allow repayment for reading in any array - for each part modular, unusually goals, but as the case may be tasks (assuredly if they can be performed in contrasting purchase order)
17. Highlight things that are not regular
18. Eat animated expression degree than unmoving agent
19. Assess to account in search the consumer’s environment in your editorial
20. In the forefront column anything, ask yourself “Last will and testament this pirate my reader?”
By way of building these practices into your documentation transform, you’ll find that your online serve becomes easier to correspond with, shorter, and incomparably very much more usable quest of your reader. What’s more, your boss will dote on you!
Tags: writing checklist, writing for the web