Writing Helpful Help – A Minimalism Checklist

 Writing Helpful Help – A Minimalism Checklist

Summary:

User documentation is all too regularly written via programmers for programmers. It tends to consciousness at the product’s functions, in place of the user’s responsibilities. Generally, programmers aren’t in the right function to be writing user documentation. They’re too near the bits and bytes, and that they’re too far from the person. To them, what the product can do has a tendency to be a long way extra critical than what the consumer can do with the product.

Keywords:

writing checklist, writing for the net

Article Body:

User documentation is all too frequently written by means of programmers for programmers. It has a tendency to focus at the product’s capabilities, in place of the user’s obligations. Generally, programmers aren’t in the proper role to be writing consumer documentation. They’re too close to the bits and bytes, and they’re too some distance from the user. To them, what the product can do tends to be some distance extra important than what the user can do with the product. 

It’s a diffused – but essential – distinction. Research shows that the key to powerful person documentation is writing venture oriented help. Even better, write your help in step with the minimalist principle. In the documentation global, “minimalism” is a flowery word for a common-sense practice. In basic phrases, it manner write in your reader and preserve it easy. 

The idea itself has a whole lot of twists and turns. If you want to read a great – however slightly wordy – e-book at the situation, check out the book “Minimalism Beyond the Nurnberg Funnel”, 1998, edited via John Carroll. 

In the intervening time, if you can tick each object inside the following tick list, you’ll be nicely to your manner to usable online help that each your readers and your managers will thank you for.

Helpful Help Checklist

1. Base the help on actual tasks (or realistic examples)

2. Structure the help based on task series – Chapter headings ought to be dreams and topics must be tasks

3. Respect the reader's activity – that is normally more about what you don’t do than what you do. Don’t waste the reader’s time by way of diving off into tangents

4. Exploit prior know-how and experience – Draw the reader’s interest to preceding tasks, stories, successes, and failures

5. Prevent errors - "Ensure you do x earlier than doing y"

6. Detect and perceive mistakes - "If this fails, you can have entered the direction incorrectly"

7. Fix mistakes - "Re-enter the route"

8. Provide error data at quit of duties in which important (rule of thumb, one mistakes information note per three duties is a superb common)

nine. Don't cut up commands with notes, cautions, warnings, and super cases - Put this stuff at the give up of the practise, anyplace feasible

10. Be short, do not spell the entirety out, specially things that can be taken as a right

eleven. Omit conceptual and notice facts where feasible, or hyperlink to it. Perhaps offer growth records on the quit of the subject, plus maybe a be aware that there are other methods to carry out the venture/aim, but this is the easiest

12. Sections must look brief and examine short

13. Provide closure for sections (e.G., again to unique screen/intention)

14. Provide an immediate possibility to act and inspire exploration and innovation (use active invitations to behave, such as, "See for yourself..." or "Try this..." rather than passive invites inclusive of, "You can...")

15. Get users started quickly

sixteen. Allow for studying in any order - make each section modular, specially desires, but perhaps duties (certainly if they can be executed in distinctive order)

17. Highlight matters that are not ordinary

18. Use lively voice rather than passive voice

19. Try to account for the person's surroundings for your writing

20. Before writing anything, ask your self “Will this assist my reader?”

By constructing those practices into your documentation manner, you’ll find that your on-line help turns into simpler to write, shorter, and some distance greater usable for your reader. What’s greater, your boss will love you!