How do you write great help docs?

February 1, 2008 1:16 PM

What are good resources for improving online help and user documentation?

I'm interested in the conceptual side here, not the software tools. What I'm looking for is books, articles or examples that provide guidelines and insight into how to write top-notch software user documentation, including online help and user guides.

posted by Palaverist to computers & internet (4 comments total)

Have you looked at the Creating Passionate Users site? If you are just starting out, you might also be interested in the Wikiversity pages for technical writing.
posted by Houstonian at 2:05 PM on February 1, 2008

Examples.

Working examples.

Lots of working examples.
posted by Caviar at 7:09 PM on February 1, 2008

Two books I can recommend:

Developing Quality Technical Information: A Handbook for Writers and Editors (IBM Press Series--Information Management)

Dynamics in Document Design: Creating Text for Readers by Karen A. Schriver

Keep an eye on these mailing lists for the occasional interesting discussion:
http://www.techwr-l.com/techwr-l-list
http://techcommpros.com/

Then there's the Journal of Business and Technical Information which sometimes has good stuff. You may be able to access it through your library, if you're not interested in purchasing articles online or subscribing.

Pay close attention to the technical documentation you come across in your day-to-day life, your car manual, IKEA assembly instructions, or even the online help included in your authoring tool. Because you're actually using that information (or trying to) you experience the quality of it. What's missing, what did you like, what were the assumptions about your knowledge and experience, were they justified or reasonable? I've always found this an edifying experience.

Also, if you're working as a tech writer, seize every opportunity to use your own documentation in anger. If you get the chance to be thrown in the deep end, say offer customer support on the products you write about or having to assist your customer's go-live, go for it! Interacting with the documentation, and more importantly, your actual audience is harshly instructive.
posted by l'esprit d'escalier at 11:16 PM on February 1, 2008

Another good book is JoAnn Hackos' Managing Your Documentation Projects. For guidelines, you need a style guide. Many software companies use the Microsoft Manual of Style (3rd edition).
posted by Houstonian at 4:24 AM on February 2, 2008