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.
The question that matters to users is not usually how to press the button, but what will happen if they do press it, and whether they should press it or not. The real task problems users have are usually with decisions, not operations.
Image courtesy of Master isolated images / FreeDigitalPhotos.net
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.
Yes, yes, yes, yes and yes. Yes.
I’ve got a blog post scheduled for today which touches on a lot of this and couldn’t agree more. Ask WHY not HOW is something I am trying to coach the team to be better at. I will be pointing them here too!
Mark: Hitting the nail on the head, as usual. I love this post.
Good and thoughtful post as usual, Mark. The other side of the coin is also there, though. In a complex system environment, instructions about tradeoffs, related concerns when assigning Setting A, etc. inevitably brings back the response from (some) users, “just tell us what we HAVE to do!”
It’s a task-based world, and plenty of people who are using the technology we are documenting are not willing to consider the myriad implications of each choice as you do, Mark. Even if it would be *better* for them in the long run to do so.
Absolutely spot on Mark.
Many years back, I got an assignment to update a help file for an ERP in Melbourne. When I saw the procedures, the first sentence was like *To approve an invoice, follow the steps below*. It was so dry, and without any context.
We always need at least some details to setup the context such as *you can approve an invoice if*, *An order is available in PAYMENTS section, only after its invoice is approved…*, and so on.
Frank: To address the concern that you highlighted, we can structure the help page with internal headings such as *About Invoice Approval* and *Steps, OR Approve an Invoice* so that users can see exactly what they are here for on this page. The objective is not to address requirements of Most Frequent Users, but of ALL users!
Funny enough, I just was thinking about just the same topic yesterday evening while driving home.
But unlike you, my conclusion was, that people hate decision making in general. Usually they have a task, when using something. They want to reach a certain goal, and they want to reach that goal now.
Usually they don’t care how something works, or what other options they could have. They want to be taught how to get from point A to point B in the shortest possible way.
I guess we’re talking about different types of documents here.
What you describe in your post, Mark, is what I call an expert reference. This reference may be part of a larger manual or a document on its own. And it only is useful for, what I call experts. An expert is someone who knows the basic and advanced use of a product already. I don’t have to tell him to press that OK button, when he wants to accept the changes.
But how do I “create” experts with my documentation?
Plain simple: At first, I don’t let the user decide anything.
I take him by the hand and tell him what to do. This is what you do with a child, too. The child (user) feels save when taken by the hand, as he can’t do anything wrong.
But just like a child, a user wants to see quick results, or he loses interest. So, if your documentation doesn’t provide those quick results, the child – sorry, the user – will end up not reading the documentation any further (damn this boring piece of paper). That’s the point where you’ve lost. Unlike with a child, you can’t get the user back to the task (reading your doc).
Documentation is therefore like a one trick pony – either it works, or it doesn’t. You only get one shot at a user, better don’t miss it.
So, how you don’t miss that shot? You give the user quick and satisfying results. That simple.
How do you do that? By not giving them any options at first.
I’ll give some examples:
– You’ve bought a new cell phone – first things you want to know: How do I insert SIM card and battery? How to start up the thing? How to call somebody? How to take an incoming call? How to use the phone book? And that’s about it. For every cell phone, no matter what extra gadgets it has.
– You’re learning a (new) programming language – first things you want to know: How to I create a program body? How do I use variables? How do I run a program? How do I create screen output? How do I get input? And this is the same for every programming language. You don’t care about any options at the beginning.
– You bought a new car – first things you want to know: How do I start the thing? Where’s the light switch? How to use the reverse gear? How do I switch on the radio? How do I open the windows? If you know all that, you’re good to go at first.
You see, these are very simple and basic questions – but every new user of a product has them. While those questions aren’t answered, a user doesn’t want to be bothered with additional information (as in “why do I press this button again?”). He just gets his answers and learns to trust your documentation, as you give him what he wants.
If you earned this trust, you’ve done everything right. The user will from now on check the documentation, if it provides the answers he seeks – this is where the reference for the experts kicks in. And for this you gave a very good example, Mark.
Here, here! I fully agree. No user document addresses the experts. Expertise is never achieved by reading documents. Documents at best, only initiate the process.
In any organization, most of the users will be task oriented, and are hardly involved in knowing or deciding. And their managers want the task to be completed first, not the questions. Even then, you may not get all the answers.
Further when many people work together for mass production/processing, standardization is absolutely necessary. So, task guidance is the concern.
I’m a technical writer, and I ask these questions to people to add value to Help . I don’t get all answers, and I’m always termed as torture!
I completely agree with the argument you make in this post. I’m wondering why I don’t do it more. I guess we’re accustomed to guidance from project managers that usually comes across as, oh, the user will know what do do; they just need instructions on how to do it in the application.
I remember working for a financial firm and providing instructions for an application dealing with short sales. It took me a while just to understand the concept of short sales. If I tried to provide business decision support, it would have probably made the firm go under. 🙂
That said, this is something I definitely need to do more in my help. Thanks for writing about this topic.
The issue about decision support depends what are you documenting. In equipment manuals, you’ll often see repair instructions listed in a decision-making table: if THIS, then THAT or THE OTHER, then do SOMETHING to decide which procedure todo. Then you’re directed toward a page that will give the procedure for the fix. If you’re documenting work for clerks, the decision making may be a proscribed to-do list, leading to the “boring” but necessary procedures. Considering the limited money people would pay for this, you probably don’t have that much room to explain more. But the decision making is there at the beginning.
But if you’re documenting software to interpret geophysically advanced seismic analysis, then you may want to explain first: which analysis method should be used, how parameters will affect results and where to get values for these parameters, and then how to interpret the results: all very decision-support related. Then again, considering how much people will pay for this type of product, and how heavy into decision making these users are (“they pay me well to make the right decisions”), you’ll have the room to add this information.
So it’s back to knowing your audience and your product.
Beautifully written. Your best post so far on this topic (and that’s saying something). Thanks, Mark.
Mark, after posting a reply to the subsequent topic, I found this one – as you might guess, I support this notion 100%.
I’m working on some interesting stuff about user assistance and cognitive development – and decision support is right up there among the topics of discussion.
Yes, yes! and Troubleshooting information.
Pingback: Incorporating Learning into Tech Comm Deliverables | I'd Rather Be Writing
Pingback: 10 Ways to Increase Search Engine Optimization in Flare | I'd Rather Be Writing
Pingback: Examples Are a Primary Way That Complicated Concepts Become Clear | I'd Rather Be Writing