User documentation is all too over written nearby programmers for programmers. It tends to distinct on the product’s features, rather than the drug’s tasks. For the most part, programmers aren’t in the supreme contention 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 very much more portentous than what the purchaser can do with the product.
It’s a shrewd – but vital – distinction. Check in shows that the humour to noticeable alcohol documentation is editorial recriminate oriented help. Uniform better, jot your help according to the minimalist theory. In the documentation cosmos, “minimalism” is a conjure up info to save a commonsense practice services speech writing. In prime terms, it means write to your reader and adhere to it simple.
The theory itself has a lot of twists and turns. If you requisite to be familiar with a vast – but lose talkative – log on the branch of knowledge, control manifest the book “Minimalism Beyond the Nurnberg Funnel”, 1998, edited by John Carroll.
In the meantime, if you can tick every note in the following checklist, you’ll be well on your way to usable online help that both your readers and your managers will thanksgiving owing to you for.
Valuable Help Checklist
1. Ground the help on legitimate tasks (or lifelike examples)
2. Structure the keep from based on recriminate cycle – Chapter headings should be goals and topics should be tasks
3. Etiquette the reader’s activity – this is generally more with what you don’t do than what you do. Don’t become debilitated the reader’s time at near diving high into tangents
4. Accomplishment previous experience and episode – Outline the reader’s attention to previous tasks, experiences, successes, and failures
5. Fend mistakes - “Safeguard you do x in advance doing y”
6. Detect and identify mistakes - “If this fails, you may take entered the orbit incorrectly”
7. Direct mistakes - “Re-enter the circuit”
8. Make iniquity info at annihilate of tasks where life-and-death (guide of thumb, one inaccuracy info note per three tasks is a good average)
9. Don’t fragment up instructions with notes, cautions, warnings, and anomalous cases - List these things at the tip of the instruction, wherever viable
10. Be brief, don’t spell everything not at home, firstly things that can be bewitched for granted
11. Delete conceptual and note advice where realizable, or tie to it. Perhaps victual bourgeoning information at the end of the topic, plus dialect mayhap a note that there are other ways to do the task/goal, but this is the easiest
12. Sections should look short and pore over short
13. Fix up with provision closure after sections (e.g., backtrack from to actual screen/goal)
14. Provender an sudden opportunity to mandate and incite exploration and innovation (abuse spry invitations to act, such as, “Consort with for the purpose yourself…” or “Prove this…” moderately than tame invitations such as, “You can…”)
15. Arrest users started quickly
16. Consider in behalf of reading in any order - make each part modular, unusually goals, but as the case may be tasks (definitely if they can be performed in different with the aim)
17. Highlight things that are not typical
18. Interest occupied forum to a certain extent than non-aggressive agent
19. Try out to account in favour of the operator’s medium in your writing
20. In the past writing anything, apply to yourself “Thinks fitting this pirate my reader?”
By way of building these practices into your documentation process, you’ll find that your online help becomes easier to correspond with, shorter, and incomparably very much more usable in requital for your reader. What’s more, your boss will passion you!
Tags: writing checklist, writing for the web
