One of the most important tools of modern business is the decision support system. Such systems can be complex and even exotic, but at its heart, a decision support system is simply a system that provides people with the information they need to make decisions.
In tech comm, we don’t talk much about decision support. We talk about task support. We frame our jobs as providing the information people need to complete their tasks. Unfortunately, what we often provide by way of task support are simply procedures for operating machines. But, as I have argued before, a task is not a procedure. In many cases, the support people need to complete their tasks is not information on how to operate machines, but information to support their decision making. Its not “how do I push the button,” but “when and why should I push the button and what happens if I do.”
In her recent article on TechWhirl, Tips and Tricks: Getting from Obvious to Valuable Technical Content, Ena Arel talks about the kinds of questions she finds herself asking when reading documentation:
As I was reading, I found myself asking “Why do I need to know this?” “What does this term really mean, and how does the corresponding concept impact my product use?” “Why did you use ‘4’ in this example? Is this the value I should use too? How do I decide what value I need to use?” “These results you are showing me, are they good? Why or why not?”
None of these questions is mechanical in nature. None of them have to do with how to push the buttons. They are all about decision making.
I have often complained about documentation that tells me everything I could work out for myself and nothing I couldn’t. The root of this complaint is generally the same: the documentation covered the physical procedure, but offered no help in making the decisions I would have to make as part of completing the task.
I’m not claiming that you never need to document the physical procedure. My field is software development, after all, and not everything in the software development world is done through a GUI. For programs, scripts, and command lines, the mechanical details of command syntax have to be clearly documented. But even where documentation of mechanicals is required, it is never enough. The real tough parts of these tasks are the decisions, large and small, that have to be made along the way — decisions as large as whether and when to do the task at all, to as small as how to choose the right value of an individual field or parameter.
Perhaps is it possible to conceive of a task for which all the decision points are so crystal clear that no decision support assistance is required, but for which the mechanical operation is so obscure that it could not be accomplished without docs, but off the top of my head, I can’t think of one.
Now to be clear, I am not talking about telling the user which decision to make. Their particular decision is obviously specific to their situation. What I am talking about is documenting the context in which the decision has to be made, or making the user aware of the consequences of the decision, and, as far as possible, leading them to resources and references that will assist them in making the decision. I’m talking about questions like:
- Where are the valid values for this field listed?
- What do each of the field values mean?
- How will system operation change as a result of this setting?
- Does this setting form part of a collection of settings that are used to achieve an overall performance objective for the system.
- What are the side effects of setting a particular value? Are there trade-offs on performance, access, or security as a result of changing this setting?
- Should this setting match a value set elsewhere in the system? If so, which value, and which is the master and which the slave?
- Are there larger questions that I should take into consideration before choosing the value for this setting?
- Will the system validate this setting? How will I know if I have chosen the right setting?
- Does my choice for this setting depend on what other users have done, and, if so, what questions do I need to ask them before I change this setting?
- Can I change this setting later, or will there be irrevocable consequences to the choices I make?
- Could this setting result in loss of data, or change how data is processed or reported?
- Who else might be affected by this setting, and what do I need to tell them about the settings I have chosen so that they can make good decisions about their own part of the system?
- How is this setting affected by optional components that may or may not be installed?
A good Every Page is Page One task topic should be mostly about these kinds of questions, and should link richly to the ancillary material that the reader may need to help them answer these questions. Only when the planning and decision making aspects of the user’s task have be thoroughly covered should the topic proceed, if necessary, to the physical procedure for executing the decisions the user has made.
Technical documentation is a decision support system. Insofar as it fails to support the user’s decision making, it fails its purpose, even if all the physical procedural steps are documented correctly.
Happily, the key to fixing this is fundamentally simple. As you write each line of the physical procedure, ask yourself, “how would the user know …?” Answer that, and document it, before you move on to the next procedural step. Then you will have a document that actually answers the real world questions that readers struggle with every day.