Building an onion

When I approach a doc set that needs a lot of work, I think of my job as building an onion. That is, creating successive layers of quality. As I build my layers I learn the doc set and the product, making the next stages possible.

The first layer is typically the result of a copy edit: remove typos and grammatical errors.

Next, work on consistency. Start to revise terminology and wording conventions (and build up a style guide). Ensure the writing is active voice, second person, present tense. Read the doc critically, thinking about the suitability of the content for the target reader.

At this stage research is required: talk to managers, product managers, developers, customer support, and customers. Look at how competitors handle similar areas. Read Wikipedia articles for background. Read the standards that your product is based on. Read analyst research for your market. And so on.

Revisit your terminology decisions, and start to formulate a clear picture of your target readers.

Create a list of problem areas in the doc set. Prioritize them.

Next, start to reorganize the content. When the organization of the ToC is good, content tends to fall into place. I especially favor a very consistent, repetitive structure. For example, each chapter (or sub-map, if you will) could have an overview, followed by sections on security, performance, best practices, and then development issues. (This will vary completely based on the subject matter.)

Revise the content by adding, deleting, and modifying. It can be difficult with pre-existing content to be brutal enough in excising junk. Sometimes I email a topic to a SME with the question, "Why do we document this?" Half the time I discover that something I thought was misguided is actually really important, and half the time I find that it's misleading and unnecessary.

Do a thorough review with a goal to tighten up the writing. Make special note of problem areas that you suspect will confuse readers. I find that in almost everything I work on, there are some parts, whether a sentence or a chapter, that need the most work. I think of them as "black holes". I can decide that most of my doc is "good enough" - which means that readers won't benefit from or even notice the result of further revision - but some areas are thorny. Frequently the black holes are in very basic, introductory content; frequently I have the sense that something is missing. Usually there are a few black holes left when I release the doc, but I keep thinking about them and working on them.

Try to have other people review the docs: peer reviews, tech reviews, editorial reviews, QA reviews, customer usability testing - whatever is possible. I favor consecutive reviews so that each reviewer sees the benefits of the previous review. It can be difficult to get people to review material that is a fixer-upper rather than dcoumentation of new features. Sometimes I try more creative approaches, like an inhouse usability test: formulate some questions that can be answered by reading the problem areas, and ask another employee to answer the questions by reading the text. Sit with them and encourage them to talk to you as they work out the answers.

When you think the doc is complete, compare it to competitor docs (if possible). Is anything missing? Which would readers like better? If a reader is familiar with the competitor's product, would they understand your terminology and approach? Tweak, tweak, tweak.

At the time of release, make a list of things you want to continue to work on when you have time. When fixing up a doc set that has problems, unless you have the luxury to throw it all out and start over, you'll probably find after the fact that there are more things you should have changed.