How do you write great help docs?
February 1, 2008 1:16 PM Subscribe
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.
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.
Examples.
Working examples.
Lots of working examples.
posted by Caviar at 7:09 PM on February 1, 2008
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
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
posted by Houstonian at 4:24 AM on February 2, 2008
This thread is closed to new comments.
posted by Houstonian at 2:05 PM on February 1, 2008