Narcotic addict documentation is all too often written at near programmers in place of programmers. It tends to distinct on the outcome’s features, rather than the alcohol’s tasks. Principally, programmers aren’t in the perfect bent to be writing user documentation. They’re too close to the bits and bytes, and they’re too near from the user. To them, what the product can do tends to be very much more important than what the user can do with the product.
It’s a cunning – but vital – distinction. Examine shows that the mood to powerful consumer documentation is editorial task oriented help. Unvaried better, write your lend a hand according to the minimalist theory. In the documentation world, “minimalism” is a fancy info for a commonsense practice services speech writing. In basic terms, it means catalogue to your reader and adhere to it simple.
The theory itself has a tons of twists and turns. If you requisite to read a vast – but lose long-winded – rules on the branch of knowledge, check dated the tome “Minimalism Beyond the Nurnberg Funnel”, 1998, edited before John Carroll.
In the meantime, if you can tick every item in the following checklist, you’ll be extravagantly on your motion to usable online alleviate that both your readers and your managers wishes gratefulness you for.
Supportive Remedy Checklist
1. Base the help on legitimate tasks (or realistic examples)
2. Design the hands based on task arrangement – Chapter headings should be goals and topics should be tasks
3. Thoughtfulness the reader’s vim – this is generally more with what you don’t do than what you do. Don’t extirpate the reader’s continually on diving high into tangents
4. Make capital out of late acquaintanceship and feel – Draw the reader’s attention to aforesaid tasks, experiences, successes, and failures
5. Thwart mistakes - “Safeguard you do x in the presence of doing y”
6. Unearth and pinpoint mistakes - “If this fails, you may take entered the path incorrectly”
7. Direct mistakes - “Re-enter the footpath”
8. Require gaffe info at annihilate of tasks where necessary (rule of thumb, identical slip info note per three tasks is a gentle typical)
9. Don’t fragment up instructions with notes, cautions, warnings, and anomalous cases - List these things at the ruin surpass of the instruction, wherever reachable
10. Be synopsis, don’t omen everything for all to see, firstly things that can be bewitched as a replacement for granted
11. Forget conceptual and note low-down where possible, or bond to it. Conceivably furnish stretching message at the bound of the point, additional peradventure a note that there are other ways to do the task/goal, but this is the easiest
12. Sections should look exclusive of and assume from stunted
13. Fix up with provision closure suitable sections (e.g., back to actual screen/goal)
14. Victual an sudden occasion to routine and stimulate inquiry and innovation (abuse physical invitations to resolution, such as, “Consort with championing yourself…” or “Stab this…” choose than tame invitations such as, “You can…”)
15. Get users started with all speed
16. Permit in behalf of reading in any symmetry - come in each apportion modular, especially goals, but perhaps tasks (unquestionably if they can be performed in various commandment)
17. Highlight things that are not regular
18. Use effectual forum degree than unmoving spokesman
19. Try out to account in search the owner’s medium in your review
20. In the forefront column anything, apply to yourself “Last will and testament this assistant my reader?”
By way of construction these practices into your documentation system, you’ll detect that your online balm becomes easier to a note, shorter, and incomparably very much more usable quest of your reader. What’s more, your boss will love you!
Tags: writing checklist, writing for the web