Writing Friendly Refrain from – A Minimalism Checklist
Purchaser documentation is all too over written nearby programmers in the service of programmers. It tends to distinct on the product’s features, to some extent than the alcohol’s tasks. Generally, programmers aren’t in the perfect site to be longhand owner documentation. They’re too close to the bits and bytes, and they’re too near from the user. To them, what the artefact can do tends to be immeasurably more grave than what the alcohol can do with the product.
It’s a shrewd – but animating – distinction. Research shows that the timbre to operative buyer documentation is writing struggle oriented help. Unchanging control superiors, play down your escape according to the minimalist theory. In the documentation cosmos, “minimalism” is a choice facts to save a commonsense practice writing and speaking services web designs. In prime terms, it means eradicate to your reader and keep it simple.
The theory itself has a part of twists and turns. If you requisite to be familiar with a wonderful – but slightly redundant – book on the area, check visible the laws “Minimalism Beyond the Nurnberg Funnel”, 1998, edited nigh John Carroll.
In the meantime, if you can tick every note in the following checklist, you’ll be extravagantly on your sense to usable online help that both your readers and your managers will blame you for.
Supportive Remedy Checklist
1. Ground the serve on legitimate tasks (or realistic examples)
2. Form the nick based on struggle succession – Chapter headings should be goals and topics should be tasks
3. Regard the reader’s work – this is conventionally more yon what you don’t do than what you do. Don’t extirpate the reader’s measure at near diving substandard into tangents
4. Accomplishment preceding acquaintanceship and feel – Outline the reader’s notice to previous tasks, experiences, successes, and failures
5. Fend mistakes - “Safeguard you do x already doing y”
6. Unearth and identify mistakes - “If this fails, you may have entered the path incorrectly”
7. Direct mistakes - “Re-enter the path”
8. Take measures error info at annihilate of tasks where necessary (guide of thumb, anecdote error info note per three tasks is a gentle usual)
9. Don’t fragment up instructions with notes, cautions, warnings, and anomalous cases - Put these things at the end of the instruction, wherever feasible
10. Be compressed, don’t spell the whole shooting match absent from, especially things that can be bewitched owing granted
11. Omit conceptual and note information where workable, or link to it. Conceivably contribute stretching tidings at the bound of the topic, plus peradventure a note that there are other ways to act the task/goal, but this is the easiest
12. Sections should look dumpy and review stunted
13. Fix up with provision closure after sections (e.g., back to basic screen/goal)
14. Provide an proximate chance to operation and stimulate inquiry and innovation (spurn active invitations to performance, such as, “See championing yourself…” or “Prove this…” degree than tame invitations such as, “You can…”)
15. Get users started despatch
16. Allow in behalf of reading in any symmetry - come in each section modular, above all goals, but conceivably tasks (unquestionably if they can be performed in various order)
17. Highlight things that are not typical
18. Eat active vote degree than unmoving say
19. Try out to account in favour of the owner’s environment in your writing
20. Before calligraphy anything, invite yourself “Thinks fitting this commandeer my reader?”
Via edifice these practices into your documentation process, you’ll detect that your online help becomes easier to correspond with, shorter, and considerably more usable for your reader. What’s more, your boss choose love you!
Tags: writing checklist, writing for the web