Consumer documentation is all too typically written by programmers for programmers. It tends to concentrate on the product’s options, fairly than the consumer’s duties. Typically, programmers aren’t within the supreme place to be writing consumer documentation. They’re too near the bits and bytes, and so they’re too removed from the consumer. To them, what the product can do tends to be way more necessary than what the consumer can do with the product.
It’s a refined – however very important – distinction. Analysis reveals that the important thing to efficient consumer documentation is writing job oriented assist. Even higher, write your assist in line with the minimalist concept. Within the documentation world, “minimalism” is a flowery phrase for a commonsense observe. In fundamental phrases, it means write to your reader and hold it easy.
The speculation itself has numerous twists and turns. If you wish to learn an important – however barely wordy – guide on the topic, try the guide “Minimalism Past the Nurnberg Funnel”, 1998, edited by John Carroll.
Within the meantime, should you can tick each merchandise within the following guidelines, you’ll be nicely in your strategy to usable on-line assist that each your readers and your managers will thanks for.
Useful Assist Guidelines
1. Base the assistance on actual duties (or reasonable examples)
2. Construction the assistance based mostly on job sequence – Chapter headings must be targets and subjects must be duties
3. Respect the reader’s exercise – that is typically extra about what you don’t do than what you do. Don’t waste the reader’s time by diving off into tangents
4. Exploit prior information and expertise – Draw the reader’s consideration to earlier duties, experiences, successes, and failures
5. Stop errors – “Make sure you do x earlier than doing y”
6. Detect and establish errors – “If this fails, you’ll have entered the trail incorrectly”
7. Repair errors – “Re-enter the trail”
8. Present error data at finish of duties the place crucial (rule of thumb, one error data observe per three duties is an effective common)
9. Do not break up directions with notes, cautions, warnings, and distinctive instances – Put these items on the finish of the instruction, wherever potential
10. Be transient, do not spell the whole lot out, particularly issues that may be taken as a right
11. Omit conceptual and observe data the place potential, or hyperlink to it. Maybe present growth data on the finish of the subject, plus perhaps a observe that there are different methods to carry out the duty/purpose, however that is the best
12. Sections ought to look brief and skim brief
13. Present closure for sections (e.g., again to authentic display/purpose)
14. Present an instantaneous alternative to behave and encourage exploration and innovation (use lively invites to behave, similar to, “See for your self…” or “Do that…” fairly than passive invites similar to, “You’ll be able to…”)
15. Get customers began rapidly
16. Enable for studying in any order – make every part modular, particularly targets, however maybe duties (undoubtedly if they are often carried out in numerous order)
17. Spotlight issues that aren’t typical
18. Use lively voice fairly than passive voice
19. Attempt to account for the consumer’s atmosphere in your writing
20. Earlier than writing something, ask your self “Will this assist my reader?”
By constructing these practices into your documentation course of, you’ll discover that your on-line assist turns into simpler to put in writing, shorter, and way more usable in your reader. What’s extra, your boss will love you!