12 Ways to Write Terrible Documentation

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.

36 thoughts on “12 Ways to Write Terrible Documentation

  1. “Usability testing is the nemesis of bad documentation”

    Beautiful. Just… Beautiful.

    Very funny and insightful, as always!

  2. I’m afraid this is me… not only scrupulously following those mandatory steps, but also my picture! How did the writer get it?

  3. Are you sure you don’t work in my office? This sure sounds like a typical day for me.

    Hilarious post. I’m printing this one for the bulletin board.

  4. Ah yes. Sounds so familiar, and makes my blood boil. Revision is indeed for suckers for many clients in this field…glad I’m not the only way who’s noticed!

  5. I’ve only just found PoeWar.com and this is the first article I’ve read – I’ll definitely be back. It’s hilarious, mostly because I think I’ve argued every one of these points with customers, managers and colleagues alike for the last fifteen years.
    It doesn’t half wear you down after a while!

  6. Pingback: When Good Clients Have Bad Ideas | Meryl.net
  7. @ Jeanne,

    Technical writing as a career can be a little soul crushing, but it has its good moments as well. I’ll be discussing the good and the bad in some upcoming posts. I hope you enjoy them.

  8. John,

    Finally got around to reading this, and I’m glad I did. Great piece! Hilarious, in fact. Still, though, it would be so much easier to laugh about it if it weren’t so annoyingly close to the truth.

    I’m glad to see that I’m not the only one who’s noticed the recent downward spiral in product documentation quality; though I’m sorry to hear that you’ve been subjected to it from the writing end, where you could have produced superior documentation materials except that your hands were tied. That’s extremely frustrating to a conscientious writer.

    It’s pretty sad for the consumer, too, though. I have to admit that I’ve watched in amazement as product documentation has grown worse and worse. These days, many product manuals barely give any information at all. Many don’t even answer basic questions that the consumer has about the product and its use and are all but worthless. And others are so poorly prepared that deciphering them would require a PhD — if even that would help (which I doubt).

    My mom recently purchased a new cordless phone setup, the manual of which (written in the world’s tiniest print) includes miniscule symbols for each button on the product — symbols which look as if they’ve been drawn freehand with magic marker (by a non-artist). The trouble is that the symbols are so tiny and the lines so thick that one can barely make out what they are. If you haven’t been through it, you can’t even imagine how irritating it is to try to figure out how to do anything at all with this phone system. (What ever happened to calling each product part by its name and then referring the consumer to the product diagram to see which part is which?)

    The current state of product documentation is absolutely horrible! And I shudder to think where our already dumbed-down documentation might go from here! I’m only glad that — though I have the analytical mind and exacting nature to write such documentation — I’ve never actually become involved in the technical writing field. The mess that well-meaning but less-than-skilled editors often make of my other articles already provides more than enough excitement — and frustration — for this nontechnical writer!

    Thanks for a great piece! :-)

  9. Hey, not sure where to ask this question. But I would like to write an eBook. Could somebody point me to any article relating to the same on this site?

    Thanks in advance…
    Ajith Edassery

    Ajith Edasserys last blog post..Bidvertiser Secrets – Optimize your Bidvertiser ads for better CPC and CTR

  10. Excellent points… this is perfect for me right now, because I am getting ready to write documentation on a few different projects… using this as a reference will help me do that more effectively for sure.

  11. @ Ajith Edassery

    I have worked with teams in Bangalore in the past, and there have been issues, especially with tools. I frequently had to walk writers through the basics of FrameMaker, and the company was dissatisfied with the speed and quality of the Bangalore team’s output. I’m not sure what the solution is.

  12. In this part of the world (Bangalore, India) it is so hard to find very good tech writers though a lot of them speak/write good English. Probably what’s missing is some of those qualities you mentioned and especially continuous learning part. In my org, we usually end up interviewing 20-25 before hiring one.


  13. I’ve taken on board the point about avoiding establishing any processes and procedures – which therefore compels me to consign this checklist to the garbage can (:-).

  14. @ Dave,

    It depends on the company, but there are plenty of them that think that way. I will say that Intuit had some nice tools that allowed them to track the success or failure of their documentation based on the decrease in tech support calls after a problem was addressed in the online help. I always respected that about them.

  15. The reality is that software vendors would love to put out no documentation at all. Documentation is a market barrier intended by large vendors to keep small software companies from doing business.

    I know of no software companies that understand that documentation, training, and technical support are what sells future releases. If they understood this, they could pay for documentation out of the savings inherent in selling to their install base.

    Ultimately, we document and teach, because the developer did not learn from the potential customers or clients, and relied on requirements and a requirements elicitation process that gurantees the delivery of average functionality. That average functionality results from political tradeoffs, so the software fits no one in particular. Somehow we are supposed to make up for that. If the requirements were specific to the individual, no manual would be needed.

    Developers abstract away from requirements, and we have to explicate back to the requirements. So many of the tasks a user must perform has nothing to do with the work they are trying to finish or the artifact that they are trying to create.

  16. Funny and helpful too. I need the help more than the comedy, though it works today, as at least 1 of 3 blogs get updated. (Not the one I left either.)

    Anywho, Shanghai thought yours was funny. I do too.

  17. This is great. I do have to write a lot for my website and I love your advices.
    Revisions are for suckers… yeah….

    services à domiciles last blog post..Conseils pour ceux qui proposent leurs services à domicile

  18. Learning is a lifetime process. It never ends.

    For a writer, or any professional for that purpose, I’d say that outlining and sketching a general map of what their plans are is quite necessary. Not only in short term, it helps in the long run as well.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>