Writing good documentation is hard. In fact it’s almost (if not just as) hard as writing good software. I am by no means an expert on documentation but do have years of experience with it. I don’t have all the answers, but over the years I’ve definitely been able to identify some bad documentation smells. The following is a list of how not to write good, usable documentation.

  1. Document every caveat, hiccup, feature, bug, and nuance of your software. Make it so detailed that users can’t find the basics. Be sure they have to read through pages and pages to understand high level themes or common operations. After all you want to make sure they read the whole thing!

    Use something like a supplemental knowledgebase or technical guide if you must document the dirty details. Keep your documentation succinct. Users will put it down if they can’t quickly find what they are looking for.
  2. Make sure your documentation is really long. Longer means better. A 1200 page user guide certainly must be more useful than a 200 page document on the same product.

    Users aren’t going to read a 1200 page document, as much as we would like them to. A document that size is simply intimidating and turns users away from the start. If all the information is critical, you likely need to break up your documentation into a more flexible format that allows linking and searching.

  3. Treat documentation as an after though. Nothing nets better documentation than just piling the responsibility on employees that already have a full work load. Even better, give them an unrealistic deadline for getting it done. You’ll be sure to have great customer facing documentation that is accurate and well organized.

    In an ideal world you would have technical writers or librarians assigned to large scale software projects. If you are using cross-functional team members make sure you have enough to get the job done. Simply put, if you want good documentation you have to make the time to get it done.

  4. Make sure your documentation process is clunky and discourages update. When you use the wrong tools and come up with a process for updating documentation that is tedious nobody will want to update it. That ensures that your documentation will grow stale and be riddled with bugs. This is certainly the best way to get your customers the most up-to-date information.

    Documentation should be easy to update. Your process should encourage feedback from stakeholders. Changes to documentation should be easy to approve and post. A convoluted process that only a couple of people have access to will prevent updates from going live. Documentation should be iterative just like software. Better yet, pipeline your documentation and release it automatically on a regular basis.

  5. Don’t give documentation any budget. If documentation is something your team finds important, make sure you don’t give it any money. That will make sure that those responsible for it will have to make do with existing resources and free tools to get it done, and get it done well. Since we are already treating documentation as an afterthought and not giving it enough time, removing money from the equation will make sure it is even better.

    Sure, good documentation can be written with free or open-sourced tools but it takes manpower. We should all be familiar with the iron triangle. If you remove time and money from the equation, scope will go down, leaving us with pretty lackluster documentation.

So what’s the solution? I’m not sure to be honest. I think what looks most appealing to me right now is treating documentation as code. Track your documentation in your VCS (git flow looks interesting for documentation), use a markup language or tool like MarkDown, Asciidoctor, or Sphinx. Finally, publish these to static HTML or PDF content on a regular basis as part of your pipeline. Now the trick is migrating all of your existing documentation. If anyone has any advice, let me know!

As always I welcome your comments and opinions.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s