Writing Useful Assist – A Minimalism Guidelines

Person documentation is all too usually written by programmers for programmers. It tends to give attention to the product’s options, somewhat than the person’s duties. Usually, programmers aren’t within the ultimate place to be writing person documentation. They’re too near the bits and bytes, they usually’re too removed from the person. To them, what the product can do tends to be much more vital than what the person can do with the product.

It’s a refined – however very important – distinction. Analysis reveals that the important thing to efficient person documentation is writing process oriented assist. Even higher, write your assist in keeping with the minimalist idea. Within the documentation world, “minimalism” is a flowery phrase for a commonsense follow. In primary phrases, it means write to your reader and maintain it easy.

The speculation itself has lots of twists and turns. If you wish to learn a terrific – however barely wordy – guide on the topic, try the guide “Minimalism Past the Nurnberg Funnel”, 1998, edited by John Carroll.

Within the meantime, in case you can tick each merchandise within the following guidelines, you’ll be nicely in your method 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 lifelike examples)

2. Construction the assistance based mostly on process sequence – Chapter headings must be objectives 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 data and expertise – Draw the reader’s consideration to earlier duties, experiences, successes, and failures

5. Forestall 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 information at finish of duties the place needed (rule of thumb, one error information notice per three duties is an effective common)

9. Do not break up directions with notes, cautions, warnings, and distinctive instances – Put this stuff on the finish of the instruction, wherever potential

10. Be temporary, do not spell every part out, particularly issues that may be taken with no consideration

11. Omit conceptual and notice info the place potential, or hyperlink to it. Maybe present growth info on the finish of the subject, plus perhaps a notice that there are different methods to carry out the duty/purpose, however that is the best

12. Sections ought to look brief and browse brief

13. Present closure for sections (e.g., again to unique display screen/purpose)

14. Present a direct alternative to behave and encourage exploration and innovation (use lively invites to behave, reminiscent of, “See for your self…” or “Do this…” somewhat than passive invites reminiscent of, “You possibly can…”)

15. Get customers began shortly

16. Enable for studying in any order – make every part modular, particularly objectives, however maybe duties (undoubtedly if they are often carried out in several order)

17. Spotlight issues that aren’t typical

18. Use lively voice somewhat than passive voice

19. Attempt to account for the person’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 much more usable on your reader. What’s extra, your boss will love you!


Ahmed Mohamed Abd ElMajeed

Web developer and Server Administrator, Founder of Akwad web School and Programmer Notes.

Related Articles


Adblock Detected

Please consider supporting us by disabling your ad blocker