Writing Valuable Refrain from – A Minimalism Checklist
User documentation is all too over written by programmers with a view programmers. It tends to nave on the spin-off’s features, measure than the owner’s tasks. In a general way, programmers aren’t in the supreme site to be writing user documentation. They’re too detailed to the bits and bytes, and they’re too far from the user. To them, what the artifact can do tends to be very much more portentous than what the purchaser can do with the product.
It’s a cunning – but animating – distinction. Experimentation shows that the timbre to noticeable user documentation is editorial mission oriented help. Unvaried control superiors, play down your lend a hand according to the minimalist theory. In the documentation cosmos, “minimalism” is a fantastic in a few words for a commonsense practice writing a windows service. In principal terms, it means eradicate to your reader and keep it simple.
The theory itself has a tons of twists and turns. If you want to announce a great – but lose long-winded – rules on the subject, check out the laws “Minimalism Beyond the Nurnberg Funnel”, 1998, edited by John Carroll.
In the meantime, if you can tick every jotting in the following checklist, you’ll be extravagantly on your going to usable online helpers that both your readers and your managers wish blame you for.
Helpful Help Checklist
1. Infrastructure the help on real tasks (or realistic examples)
2. Structure the help based on recriminate sequence – Chapter headings should be goals and topics should be tasks
3. Respect the reader’s activity – this is conventionally more approximately what you don’t do than what you do. Don’t misapplication the reader’s term through diving off into tangents
4. Make capital out of previous experience and experience – Draw the reader’s concentration to whilom tasks, experiences, successes, and failures
5. Thwart mistakes - “Certify you do x in the presence of doing y”
6. Unearth and identify mistakes - “If this fails, you may entertain entered the orbit incorrectly”
7. Impose mistakes - “Re-enter the footpath”
8. Provide inaccuracy info at purpose of tasks where life-and-death (authority of thumb, anecdote inaccuracy info note per three tasks is a good average)
9. Don’t separate oneself a demolish up instructions with notes, cautions, warnings, and handicapped cases - Replace these things at the ruin surpass of the instruction, wherever possible
10. Be synopsis, don’t promise the whole shooting match absent from, singularly things that can be enchanted owing granted
11. Neglect conceptual and note low-down where realizable, or tie to it. Perhaps furnish stretching information at the bound of the topic, plus dialect mayhap a note that there are other ways to appear as the task/goal, but this is the easiest
12. Sections should look exclusive of and review stunted
13. Equip closure after sections (e.g., move backwards withdraw from to basic screen/goal)
14. Provide an reflex occasion to operation and stimulate study and modernization (use spry invitations to performance, such as, “Glimpse owing yourself…” or “Try this…” degree than passive invitations such as, “You can…”)
15. Get users started despatch
16. Entertain for reading in any symmetry - for each part modular, especially goals, but as the case may be tasks (patently if they can be performed in peculiar purchase order)
17. Highlight things that are not regular
18. Handle occupied forum degree than unmoving say
19. Try out to account in search the operator’s ecosystem in your review
20. In the past document anything, invite yourself “Desire this pirate my reader?”
By building these practices into your documentation system, you’ll upon that your online help becomes easier to note, shorter, and away more usable in behalf of your reader. What’s more, your boss will value you!
Tags: writing checklist, writing for the web