Twelve Ways to Write Terrible Documentation

 Twelve Ways to Write Terrible Documentation

March 12, 2008 by By John Hewitt

 When I began my technical writing career, I was under the impression that companies valued good documentation. After twelve years in the industry, I can assure you that is not the case. Judging by the documentation I have seen and the documentation I’ve been asked to produce, companies would prefer to put out unmanageable manuals and meager guides. Realizing this, I have decided that they should have their own set of instructions — a sort of quick reference guide for bad documentation. In keeping with their style, I have chosen to write this quickly, and avoid numbering the steps.

• Never outline what you are planning to develop.

Outlines give you structure and help you to organize your thoughts. That is just the sort of thing you want to avoid. Always write on the fly.

• Learn as you write.

Clients are learning as they read; you should approach your documentation the same way. As long as you’ve figured it out by the time you finished, you’ll be fine. Even if you don’t, if you throw enough words at the problem, the reader will get bored or frustrated long before they figure out that you don’t know what you are talking about.

• Avoid graphics.

especially explanatory ones. A picture is worth a thousand words, so throw a thousand words at it instead.

• Embrace inconsistency.

Every time you write about the same process, approach it a completely different way. Stay away from style guides, standardization and repetition at all costs.

• Edit sparsely.

Editing is like smoking. If you’re editing now, stop. If you haven’t yet begun to edit, don’t start. This goes for peer reviews too. Avoid them if you possibly can. They’ll only make you change stuff.

• Avoid white space.

Good visual design is far too helpful. Readability is your enemy. Crowd as much text onto the page as you possibly can. Long paragraphs are the way to go.

• Create as unreasonable a schedule as you can.

If you have a product that you need documented, don’t even think about giving the writer more than a few days. Sure, it took you sixteen months to develop the product, but it should only take six hours to document it.

• Start the documentation as late in the process as possible and end it as early in the process as possible.

If you have a ten-month development cycle, contact the documentation people after about eight months, but make sure they have to get it out before the product is finished. The more features you change after the manuals are out, the more frustrating the documentation will be. The customers will hate your product (they probably would have anyway), but you can blame the whole thing on the documentation.

• Use Microsoft Word.

Microsoft Word has the ability to crash while creating a table of contents. For longer documents, it often loses pages. Even better, the automatic numbering feature appears to have been created by dyslexic boll weevils. A random lost page and a bad table of contents will go a long way toward reaching your customer dissatisfaction goals, but inconsistent numbering will really put you over the top.

• Avoid establishing any processes or procedures.

Procedures create repeatable results and avoid confusion. Processes can only hurt the documentation if they are unnecessarily complex or completely inappropriate for what you are doing. That is a lot of work to go to just to screw up your projects. It is easier to keep things nice and random. That will screw the documentation up with a minimum of effort.

• Never pay for usability testing.

Usability testing is the nemesis of bad documentation. Actually letting the people who use your product have a say in the documentation (or god forbid the actual product) will result in unwanted improvements and increased customer satisfaction. Luckily, most companies avoid usability testing the way democrats avoid cohesion and unity, so it shouldn’t be a problem.

• Once your manual is produced, forget about it.

Revisions are for suckers. Products come and go, but bad documentation blows and blows.