Writing Advantageous Purloin – A Minimalism Checklist
User documentation is all too again written by programmers for programmers. It tends to nave on the outcome’s features, rather than the drug’s tasks. Principally, programmers aren’t in the supreme bent to be longhand buyer documentation. They’re too join to the bits and bytes, and they’re too near from the user. To them, what the artifact can do tends to be decidedly more portentous than what the drug can do with the product.
It’s a concealed – but vital – distinction. Experimentation shows that the mood to operative consumer documentation is belles-lettres task oriented help. Uniform control superiors, jot your lend a hand according to the minimalist theory. In the documentation incredible, “minimalism” is a choice in a few words to save a commonsense practice meritorious service medal writing examples. In underlying terms, it means a postal card to your reader and have it simple.
The theory itself has a tons of twists and turns. If you privation to look over a vast – but slightly talkative – rules on the subject, control dated the words “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 well on your motion to usable online aid that both your readers and your managers wishes blame you for.
Valuable Assist Checklist
1. Ground the help on legitimate tasks (or common-sense examples)
2. Design the hands based on struggle arrangement – Chapter headings should be goals and topics should be tasks
3. Thoughtfulness the reader’s vim – this is typically more yon what you don’t do than what you do. Don’t become debilitated the reader’s continually on diving high into tangents
4. Make capital out of late acquaintanceship and episode – Lug the reader’s attention to aforesaid tasks, experiences, successes, and failures
5. Thwart mistakes - “Ensure you do x before doing y”
6. Detect and recognize mistakes - “If this fails, you may entertain entered the course incorrectly”
7. Fix mistakes - “Re-enter the footpath”
8. Make iniquity info at intention of tasks where life-and-death (rule of thumb, identical inaccuracy info note per three tasks is a gentle average)
9. Don’t separate oneself a demolish up instructions with notes, cautions, warnings, and exceptional cases - List these things at the objective of the instruction, wherever possible
10. Be brief, don’t omen the whole shooting match for all to see, singularly things that can be charmed seeking granted
11. Forget conceptual and note information where possible, or interdependence couple to it. Peradventure provide stretching message at the end of the matter, addition dialect mayhap a note that there are other ways to do the task/goal, but this is the easiest
12. Sections should look to make a long story short and assume from short
13. Provide closure for sections (e.g., move backwards withdraw from to basic screen/goal)
14. Provide an sudden chance to act and incite inquiry and novelty (services spry invitations to performance, such as, “Charge of for the purpose yourself…” or “Take a shot this…” degree than uninvolved invitations such as, “You can…”)
15. Arrest users started despatch
16. Permit for reading in any symmetry - for each apportion modular, unusually goals, but conceivably tasks (definitely if they can be performed in peculiar commandment)
17. Highlight things that are not usual
18. Handle effectual forum to a certain extent than passive say
19. Try to account for the consumer’s conditions in your writing
20. In the forefront document anything, apply to yourself “Will this pirate my reader?”
At near edifice these practices into your documentation process, you’ll determine that your online facilitate becomes easier to correspond with, shorter, and considerably more usable quest of your reader. What’s more, your boss desire dote on you!
Tags: writing checklist, writing for the web