November 2009 | HelpScribe

Technical writing books everyone should own

Here is a list of essential technical writing books, covering both theory and practice and written by industry professionals. Are they on your shelves?

Technical Communication: A Practical Approach (7th Edition) (William Pfeiffer and Kaye Adkins)
Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content (Alan Pringle)
Developing Quality Technical Information: A Handbook for Writers and Editors (2nd Edition) (Multiple authors)
Technical Editing: The Practical Guide For Editors And Writers (Hewlett-Packard Press) (Judith Tarutz)
Effective onscreen editing: new tools for an old profession (Geoff Hart)
Conversation and Community: The Social Web for Documentation (Anne Gentle)
Content Management for Dynamic Web Delivery (JoAnn Hackos)
Managing Writers: A Real World Guide To Managing Technical Documentation (Richard Hamilton)
The Chicago Manual of Style
Microsoft Manual of Style for Technical Publications (Microsoft)
Technical Writing Management: A Practical Guide (Steve Schwarzman)

You can buy the books here.

Also, don't forget to search online sources for books that have been released for viewing completely free of charge. For example, check out Online Technical Writing by David McMurrey. It is filled with valuable information on crafting technical documents, and has examples and guidelines for various kinds of documents.

These books cover many aspects of the day-to-day work of technical writers; style guides, management advice, documentation strategy, and more. Staying competitive in this field means keeping your skills up to date and staying abreast of changes in technology and best practices; reading is a great way to accomplish that goal.

When minimalist documentation stinks like old cheese

Today I'm staring at an assortment of new brake parts for my car. My caliper pins are gunked up, so I have to fix them, or continue listening to the awful grinding noise they make when I hit the brakes.

I know what to do with most of these parts. You see, my dad was a certified brake mechanic, so I've learned a trick or two. However, one tiny detail is outside of my current realm of knowledge.

How do those bushings and O-rings fit together so that they don't allow brake dust to build up inside the pin mechanism?

To solve the bushing and O-ring mystery, I'll be consulting my Haynes repair manual. (I could probably figure it out by just staring at the parts for a while, but I want to be sure; this is the second time my caliper has froze in the last few months.)

I don't care what the manual says about filling the coolant tank, rotating the tires, or even possible causes for brake noise. I already know what the problem is.

I only care about one single detail... how those bushings and O-rings fit together.

Perhaps many of our users are in the same situation. They don't care about our well-crafted overview topics. They are looking for a needle in a haystack. If we've covered the one tiny detail they seek, we'll make their day, and they'll learn to trust our documents.

That's why I own a fat stack of Haynes manuals. They always cover exactly the details I'm searching for.

It's also why I'm such a big fan of FAQs.

Technical writing is about covering the essential details, and making sure users can find them. A manual that answers the wrong questions is just a waste of tree pulp.

Adding screenshots in help topics

Here are a few tips for adding screenshots to your help topics.

Use contrast

Use a high-contrast color for callouts, arrows, and other elements that reference screenshots. Avoid any color that is heavily used in the screenshot.

I often see black callouts over screenshots with black interface elements. Such visual elements are hard to see because they blend in with the screenshot. If your callouts require black text, consider using a background color with some alpha transparency applied.

Crop for improved focus

Use the crop tool in your image editor to focus the screenshot on the elements being discussed in the text. Don't bother showing the entire screen when you really need to zoom on a small section of the interface. Help windows often limit your real-estate for screenshots, so cropping helps you to show what you need to without introducing horizontal scroll bars.

However, don't crop out so much that your reader can't determine the context of the screenshot.

You can hyperlink a cropped screenshot to a larger view of the entire screen. That way you maximize real-estate within the topic, and still offer viewers the full screenshot if they are interested.

Use CSS borders and padding

Add borders and padding to your screenshots to add a professional look and set them apart from the text. Use CSS to apply the border and padding settings to the IMG tag. That way you only have to do it once.

Don't forget ALT text

Add an ALT attribute to your images, and use descriptive text. The text should be long enough to serve as a summary for the concept presented by the image.

The ALT tag helps visual learners grasp a concept quickly without reading the boring details. (Like it or not, some users will ignore your help text and skim for images and headings that hint at the details.) Also, the ALT tag will give your images greater search visibility if your help is posted on a server.

That's all for now.

For some great advice on deciding when screenshots are worthy of inclusion in your documents, check out Screen Shots in Documentation by Michael Hughes.

Related: