The most basic documentation is the help file that ships with the product. In Microsoft products, this is called a .chm (“chum”) file. Yes, I’ve probably thought of my share of bad jokes about that slang, too. I find myself currently involved in cleaning up the previously written .chm file for a new product as well as authoring new content for it and there have been some challenges.

Out of these challenges have come the start of my own personal list of DOs and DON’Ts for technical documentation.

• DO know your consumer and know HOW they use the product to do their jobs.
• DON’T sacrifice your reference sections in favor of only user story or scenario-based content.
• DO use a more conversational voice to make the documentation easier to consume.
• DO review customer feedback for opportunities to update your documentation to cover problem areas when appropriate.
• DO produce other documentation besides just the .chm help files.
• DON’T use the excuse of having other documentation to short-change the help files.
• DO edit for professional voice and errors.
• DON’T over-edit and lose technical accuracy in favor of prettiness of language.
• DO offer tips and make sure gotchas are included.
• DO make content easily findable and clearly identifiable by the consumers.
• DO have your content thoroughly reviewed by the product team.
• DON’T let the process of creating documentation get in the way of doing the right thing for the customer.

My background in shipping products has given me some valuable insight and gives me a solid base on which to work with the product team. I understand what they are talking about and don’t need a lot of hand-holding. They know I take deadlines seriously and am honest with them about where I am on my deliverables.

But I think documentation teams also really need to be able to turn on a dime. Things can change rapidly and you have to be able to roll with those changes.

Processes are required, both within the documentation team and where the documentation team has to interact with the product development team, but you really have to watch for signs that the process may be causing more overhead and pain that it’s solving. When a five minute task takes three days, an email thread of ten or more emails plus several requests being filed…you may have a problem.

You have to keep your eyes on the prize. The prize is excellent documentation to assist your consumers – not how well processes were followed or how many you have. No one will judge your documentation by how many people worked on it, how many processes were followed, who did what tasks or what tools were used to produce it. All consumers care about is how well it meets their needs.