Writing Documentation That Doesn't Suck

I've often had to write manuals for the products I've developed. The Technical/Maintenance manual is easiest (because the audience is technical), and the User/Operations Manual is by far the hardest (anyone can be a user).

Like many engineers, I took the minimum number of required writing classes.  So it was not a huge surprise that my initial attempts at product documentation were terrible.  Over time I finally became "not horrible" at documentation, and the main path to success was to avoid saying too much!

There are many technical writing guidelines online, but I find most are too narrowly focused to be of general use. A few simple guidelines are generally enough to avoid documentation disaster.

Here are some guidelines that have served me well:

• "Don't write so that you can be understood, write so that you can't be misunderstood." William Howard Taft

This is partly about getting inside your reader's head, and partly about getting out of your own. It is all too easy to write for people who are near-clones of yourself, and forget the wide range of other folks on the planet.

It's about making your writing as "simple and obvious" as possible. Avoid long-winded explanations when a couple short, carefully-crafted sentences will do the job. That said, always use however many words are needed to make each point clearly and concisely.

Important things may need to be said more than once. What I typically do is "say it once", then show an illustration, then explain the illustration, and finally summarize what was just done (what success looks like).

• Have some "fresh eyes" available.

Given that we can't understand all possible readers, we must remember that we only truly care about the first-time reader. That means at least some of the folks who review our work must also be as close to a first-time reader as possible.

In particular, this means it must be simple and easy for actual users to provide feedback on the manual itself. Encourage each customer to print and mark-up the instructions, and tell them how to get their input back to you (email, forum, etc.).

• Include a glossary.

It is way too easy to use too many technical terms, and too hard to get rid of them. Having a glossary and always keeping it current is a great way to track specialty terms and language.

• Don't get tied down to a Table of Contents: Make it the last thing you generate.

Too many folks start with a Table of Contents as the plan for the document. This is backwards! The document should have whatever organization and structure it needs to get its job done, and the flow is expected to change with time.

That said, it is important to have a "ToDo List" for the document, a detailed set of goals for what must be included and not left out.

Of course, organization is needed, but primarily at the lower levels:
o What is the purpose of this step?
o What tools and parts are needed to accomplish this step?
o What things must I do?
o How can I verify that I did it correctly?

• There is no such thing as too many good illustrations.

However, there is such a thing as too many bad illustrations! The old saying "A picture is worth a thousand words" isn't totally wrong, but having a picture doesn't mean words aren't necessary. Illustrations should add context and meaning to words, not replace them.

For something like kit assembly, there are going to be situations that words can't express in an understandable way. This is when illustrations matter most, so take the time to create lots of candidates and choose the best. Try to avoid the "one and done" attitude to images or drawings.

• Layout matters! But not until close to the end.

One important goal is to not force the reader to have to flip back and forth between pages to understand what's going on. Text mixed with images? Images and text in separate columns? Size? Pagination? These are all important to the reader, but not unless and until the needed information is already present in the document.

• Documentation is really about "teaching", not "telling".

The user has goals, and the documentation must ensure the user will meet those goals with minimal confusion, and minimal need to ask for help. For kit assembly, the initial steps should train the user to become a good assembler, not merely get things put together.

Not all of us learn in the same way, and there are a number of ways by which we learn. These ways are called "learning modalities" (or "learning styles"), and while we all have access to all them, some work much better than others, and which ones do best will vary between individuals.

It is often necessary to say a thing in different ways (words, pictures) in order to engage multiple modalities. It is also important to help the user sharpen the modalities that will be most useful, and that's where training comes in. Take time at the start to build the skills the user will need before making use of them. Even the fundamentals matter:
o What is an "M4 screw"? Is a screw different than a bolt?
o What does it mean to "tighten a screw"? How tight is tight enough? How tight is too tight?
o What does it mean to "crimp a connection"? How can I tell if I did it right?