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.
- etc…
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.
- etc…
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.
Summary
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.
Scott – This post is so timely for me! I’m currently reworking the doc set for our product (Accept 360°) with these goals (and a lot of Kathy Sierra’s ideas) in mind. It’s a big change, and somewhat scary – not much of the current docs will be left by the time I’m finished, so it’s all new work — but I know it will provide a lot of value for customers and prospects evaluating the product.
Hooray!
Thanks Nils, you’ve made my day!
And good luck with the doc, I think you’re right – it will help a ton. Did you also check out the Use Case Driven Documentation article?
Your articles is right on target. I couldn’t agree with you more. Unfortunately, the principle in software is to write only about the tool, and not the job, because we in software can’t really know what the actual job in a company might be. Somewhere, software requirements folks determined this was the correct approach. I argue with this all the time in developing help for software systems. So I agree with you. However, your article lacks research or specific information about users preferences for help, what works and what doesn’t. Your logic, however clear to me, won’t convince my managers.
Coming very late to the party–sorry, I just stumbled on this post. But, why not do both? Why are you making it about job vs. tool as if we were only allowed to write about one?
I want to know how to use the tool. I want to know everything about how it works. And I want to do the job. Because you know what, one day, with what I know about the tool and my own work, I will either come up with a better way to do my task than you did, or I will come up with a task you didn’t consider, or both.
Great point, Debbie!
The key thing is to write the documentation your users/readers want. I clearly assumed it would be “do the job” docs, not “understand the tool” docs. A good reminder that understanding what your users need / want should guide how you write the documentation.
Great post! However, I wonder if this is suitable for users who are beginners. We are assuming prerequisite knowledge of the tool here. They’d want to understand the tool, right? I do agree that getting the job done is a priority is for most of the users. But how about the users who don’t know anything about the tool? We could introduce the feature first and then add some use cases.