The service manuals of yore

When I gave up my workbench and oscilloscope in the R&D lab for a desk in Field Service Technical Publications, I learned to structure product service manuals in this way:

• Introduction
• Theory of operation
• Controls
• Removal/replacement/adjustment procedures
• Field-replaceable units
• Installation procedures
• Fault isolation tables
• Technical specifications

This was the One True Structure, handed down from on high. (I think it was probably carved on stone tablets, but since I didn't work at headquarters, I never saw them.) Nobody questioned The Structure. Nobody asked whether it made information easy to find.

In truth, it was worse than that. "User-friendly" was a derisive epithet, uttered with a sneer. Were our field service engineers such a bunch of babies that they couldn't handle a proper 350-page service manual?

My goodness, how the profession has evolved since then. How our philosophy has evolved!

Sometimes I wish I could go back and rewrite my first manual using what I know now, and lead my benighted colleagues into the light. Great material, bad sequencing, I would tell them. Shorten the introduction to one page maximum. If our field engineers missed training on this product, they still know a printer when they see one, so just hit the high points. They're our engineers; you don't have to sell it to them. Installation procedures next. Then controls. Testing and fault isolation. Removal/replacement/adjustment procedures; roll the information about field-replaceable units into that chapter. Performance verification and technical specs last.

The clouds would part and angels would sing when the field engineers found that they didn't need to skip all over the book to find the bits they needed. O, for a time machine to let me go back and light the way.

Bah.
Our whole profession marched boldly forward, through the dark times and into the light. We thought things through. We learned from each other and taught each other. Those ponderous 300-page manuals that seem to have neither rhyme nor reason are a thing of the past. We learned a new word: usability.

We technical communicators grade our work now on the percentage of help desk calls that are due to actual product malfunctions or defects rather than issues that our customers can resolve on their own. It's still important that the relevant information be documented, but now we know that information is only useful if you can FIND it.

We got there. No time machine required; just the magical alchemy wrought by time itself - time, and passion for communicating technical information clearly.

Getting out of the box

Anybody can write - right?
Sure.
But do you want just anybody writing the help or the administrator's guide for your product?

Your product development team has worked hard to bring a vision into being. You wouldn't have spent the time and effort on it if you didn't believe - passionately - that the project could meet your customers' needs in a way no other product can do. Your team wouldn't have put their hearts and souls into developing this product unless they believed in it. Doesn't your team deserve to have their brilliant work showcased? To put that another way: Shouldn't you give this product the best possible shot at success?

Great product documentation shows your customers how simple it is to use your product, and makes them want to try out all its features. Because as complex and sophisticated as the design may be, as elegant as the code may be, what's going to sell your product is the perception that it's robust, reliable, and easy to use. Great product documentation gives your customers the confidence to get familiar with the product - and once they've cleared that hurdle, the product looks a lot easier to use.

What does great product documentation look like? Like Supreme Court Justice Potter Stewart, you probably know it when you see it. But what is it that you see?

In great documentation, you see little about the product's capabilities or design philosophy. Instead you see information about how people can use the product to accomplish what they want to do. It's about your customers first.

It's easy to make the business case for top-notch product documentation - be it installation drawings, administrator's guides, quick tip sheets, or help: If that's part of the package, you'll win more competitive evaluations, and you'll spend less on technical support. And amazing as it may be, it takes fewer words and less time to communicate the people-centric information that your customers need than the design-centric material that they dread - so even the direct cost of creating great product documentation is lower than the direct cost of creating lower-quality material.

Move your product documentation out of the box. Put it on the winner's platform - along with your great product.