Comments on: How do you write great help docs?

Question: How do you write great help docs?

Palaverist — Fri, 01 Feb 2008 13:16:09 -0800

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.

By: Houstonian

Houstonian — Fri, 01 Feb 2008 14:05:28 -0800

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.

By: Caviar

Caviar — Fri, 01 Feb 2008 19:09:57 -0800

Examples.

Working examples.

Lots of working examples.

By: l'esprit d'escalier

l'esprit d'escalier — Fri, 01 Feb 2008 23:16:47 -0800

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.

By: Houstonian

Houstonian — Sat, 02 Feb 2008 04:24:55 -0800

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).