Why do we write documentation? Because someone told us to write it? Because our competitors have it? Or because we want our software to be easier to use? It should be the third one, but often, writing documentation is an afterthought, and it is deprioritized, and we just get it done, instead of thinking about the goals for doing it in the first place and doing it right.
Instructions for a Drill
Imagine that the instructions for your brand new electric drill had the following sections:
- How to adjust the speed of your drill.
- How to change the direction of the drill.
- How to change the drill bit.
You wouldn’t know very much about how to accomplish something with the drill – you would only know how to operate the drill. What if the instructions had the following sections:
- How to drill a hole in a flat surface (wood or plastic, metal, masonry).
- How to select the right screw for fastening items.
- How to drive screws (phillips, flat-head) with your drill.
- How to stir paint with your drill.
Suddenly, the documentation is helping us to achieve our goals.
Do The Job (Versus Use The Tool)
We write documentation so that people can more easily do the job, not so that they can use the tool. In our example above, the “use the tool” instructions in the first list would be fine for someone who already knows how to use a drill – it would only teach them the unique elements of how to use this drill.
Software doesn’t present the same set of physical affordances that hardware does. Rarely are there a handful of obvious physical controls begging for interaction – “That looks like a trigger, and the drill looks like a gun – I bet that’s how I make it spin!”. Instead, we have a myriad of choices – buttons, menus, hidden context menus, command line prompts, gestures, etc.
With rare exceptions, we aren’t writing documentation to teach someone how to use our software (instead of some other software they already know, which does exactly the same things). We are trying to teach them how to achieve their goals and solve their problems, using our software.
We defined requirements to solve problems and achieve goals and generate value. Shouldn’t our documentation be written with these same goals in mind?
Creating Competent Users
We’ve written before about Kathy Sierra’s now famous suck threshold. The suck threshold is the minimum level of competence required for a user to feel like they don’t suck when using the software. We talked about it in the context of defining the right number of features to include in the software. More features means more complexity which means users take longer to master the software.
We’ve also talked about how to prioritize features for software to maximize the likelihood that our users will operate above the suck threshold. We have to prioritize for competent users (people above the suck threshold) because beginners aren’t beginners for long, and few people invest the time and effort to become experts.
A key articulation users propose for why software sucks is that they can’t understand how to achieve their goals.
Our Documentation Should Help Users Achieve Their Goals
Pretty simple, really. Many software “manuals” have documentation that is organized to mirror the user interface – a section for each menu, with a sub-section explaining how to use each item in the menu (“How to adjust the speed of the drill”). It is left as an exercise for the user to know when, why, and how much to adjust the speed of the drill. These gaping voids provide a great market for authors – how many trees have died to publish “How to use Access” and “Secrets of Word” and “Excel for Dummies?”
Thankfully, there are good examples of documentation out there. Subversion, open source source-control software, has goal-driven documentation. It serves as a great example, in that the documentation (an open-source book, really) shows how to use subversion to achieve particular goals (how to migrate from another solution, how to restore my old file, etc), or how to set up subversion to operate in particular situations.
Goal-driven documentation effectively lowers the suck-threshold. It allows us to include more features (because we can more easily ignore them, and because we can see how and why we might use them, instead of just understanding how they operate). Goal-driven documentation also accelerates the user up the learning curve, allowing them to be productive far more rapidly.
Write goal-driven documentation. It helps users achieve their goals using the software. This creates more competent users more quickly. And it helps generate evangilists and salespeople within the user community.