I’ve just spent 6 months doing editorial review of software documentation for several different projects. I think I’ve come out of this with some insights into the common missteps we make with documentation which I am going to call “documentation anti-patterns”1. I have a long list of these which I intend to write about here overtime, but they mostly come down to losing sight of your audience and your objectives (or not having a clear idea of these to being with) and therefore not being able to evaluate your success.
Documentation Anti-Pattern #1: Writing “about the product” instead of “for the users”
One piece of content I reviewed recently was a “how to install the product” type procedure where the installer was a command-line tool. This was a huge procedure with 27 steps, and several of those steps had up to 10 sub-steps, and some of those even had a few sub-sub-steps. So procedure really had over 50 individual steps. It was over a dozen pages in length.
So you would think this must have been a very complicated installation process then? Well, no. You ran the command line tool and it prompted you for which components to install, one by one with a prompt for yes or no, and then it prompted you for each configuration detail with pretty clear descriptions in the prompts. The procedure had so many steps because every single prompt had it’s own procedure step with an expanded description, an illustration of what that prompt looked like, and often a short explanation of the function of the component.
This procedure could have been shortened into probably 10 steps that each summarized a logical set of prompts, followed by a reference table that detailed each prompt and the requirements and defaults for it.
So what went wrong here?
Someone wrote a reference guide to the installer instead of user instructions about how to install the product.
They wrote documentation “about the product”, instead of “for a user”. It’s a subtle distinction but a powerful one. It’s very easy to “document all the facts” about a system or product and never actually create documentation that helps people do things.
It’s easy to lose sight of the purpose of your documentation and who your audience is. This requires constant vigilance. For each piece of content you are working on, write down a statement of who the audience is and what it is supposed to help them do. Get it verified for correctness, and constantly refer back to it to make sure you are on track and haven’t started to deviate.