User documentation is all too often written by means of programmers for programmers. It tends to consciousness on the product’s features, in place of the person’s responsibilities. Generally, programmers aren’t in the best function to be writing consumer documentation. They’re too near the bits and bytes, and they’re too a ways from the person. To them, what the product can do tends to be a long way extra important than what the user can do with the product.
It’s a subtle – but vital – distinction. Research shows that the important thing to powerful person documentation is writing task oriented assist. Even better, write your help in keeping with the minimalist concept. In the documentation world, “minimalism” is a elaborate phrase for a commonsense practice. In basic terms, it approach write for your reader and maintain it easy.
The idea itself has loads of twists and turns. If you want to examine a first-rate – but barely wordy – e-book at the concern, check out the e book “Minimalism Beyond the Nurnberg Funnel”, 1998, edited by John Carroll.
In the intervening time, if you can tick every item in the following checklist, you’ll be well for your way to usable on-line assist that each your readers and your managers will thanks for.
Helpful Help Checklist
1. Base the assist on real responsibilities (or sensible examples)
2. Structure the assist based on mission collection – Chapter headings should be goals and topics have to be obligations
3. Respect the reader’s hobby – this is commonly greater approximately what you don’t do than what you do. Don’t waste the reader’s time by diving off into tangents
4. Exploit earlier information and revel in – Draw the reader’s attention to previous duties, reports, successes, and screw ups
five. Prevent mistakes – "Ensure you do x before doing y"
6. Detect and discover errors – "If this fails, you could have entered the direction incorrectly"
7. Fix errors – "Re-input the direction"
8. Provide errors info at cease of obligations wherein necessary (rule of thumb, one mistakes info note according to 3 obligations is a good common)
9. Don’t cut up commands with notes, cautions, warnings, and high-quality instances – Put these things on the quit of the practise, anywhere possible
10. Be brief, don’t spell the entirety out, specially matters that may be taken with no consideration
eleven. Omit conceptual and word information where feasible, or hyperlink to it. Perhaps offer growth records on the cease of the subject, plus maybe a observe that there are other approaches to carry out the assignment/aim, but that is the easiest
12. Sections should appearance brief and examine brief
13. Provide closure for sections (e.G., lower back to original display/purpose)
14. Provide a right away opportunity to act and inspire exploration and innovation (use active invites to act, along with, "See for yourself…" or "Try this…" rather than passive invites along with, "You can…")
15. Get customers began speedy
sixteen. Allow for studying in any order – make every section modular, mainly dreams, however possibly responsibilities (clearly if they may be completed in distinct order)
17. Highlight matters that are not standard
18. Use lively voice in place of passive voice
19. Try to account for the user’s surroundings for your writing
20. Before writing some thing, ask your self “Will this help my reader?”
By building those practices into your documentation manner, you’ll locate that your online help will become simpler to write down, shorter, and some distance extra usable in your reader. What’s more, your boss will love you!
