The purpose of technical communication is not to translate complex information into simple terms, but to enable the reader to act correctly.
Tom Johnson has a great blog post laying out An argument for complexity rather than simplicity in technical communication. Many products, Tom argues, are complex, and to pretend otherwise is to do the reader a disservice. I have great sympathy with this argument, complaining, as I often do, about documentation that explains everything you could figure out for yourself, but nothing else.
Tom begins by quoting the revised STC mission statement, which defines technical communication as “the discipline of transforming complex information into usable content for products, processes, and services” Tom praises the STC for choosing to use the word usable rather than the word simple.
What’s interesting is the choice of the term “usable content.” Sometimes I see definitions of technical writing as “simplifying complexity,” or “making difficult ideas simple,” or something along those lines. The idea is that technical writers take a mountain of complex information and somehow transform it into something really simple and easy to follow — as if technical writers had enough genius to see through complex lines on a map and find a clear, simple path from point A to point B.
I’m certainly with Tom on this, but I’m still not happy with the STC’s definition. I don’t like any definition of technical communication that portrays it as somehow being about the transformation of existing information. Transformation is the wrong model, for a couple of reasons:
- It suggests that the body of information to be transmitted to the user is defined and compiled by others and then passed on to the technical writer to be transformed or translated into something the user can understand. But the body of information created about a product during the product management and product development phases (which is what the writer has to work with) contains a huge amount of information that is of no interest to the user, and omits a great deal that is of interest to them. In fact, the overlap between the two information sets can be quite small. A good tech writer does research and creates new content. They do not translate or transform anything.
- It suggests that the task we want the user to perform is to comprehend a piece of information. But as anyone with any experience of the school system or its recent graduates can tell you, the ability to comprehend information does not imply the ability to act correctly in real world situations. Comprehension of texts is not the goal. The goal is correct action in the real world.
My definition of technical communication, therefore, goes something like this: Technical communication creates content that assists the user to act correctly with a product or service.
Focusing on correct action helps to cut through any debate about simplicity vs complexity. Some actions are simple. Some are complex. Some are simple to perform but have complex consequences that have to be understood to act correctly. Some have simple consequences but require complex procedures. Some are complex in both procedure and consequences. Documentation needs to provide the appropriate support for the particular mix of complexity and simplicity in the case at hand.
There are a couple of caveats to this, however. The first is that you don’t want the content to so intimidate the reader that they abandon the task. As I discuss in my book, Frankenbooks can be particularly intimidating. We should attempt to present content in a less overwhelming manner, which almost certainly means not rubbing the user’s nose in how big the documentation set is. Fortunately, modern Web tools give us powerful ways to create documentation sets that look simple while still providing comprehensive coverage.
An intimidating doc set can do more harm than simply scaring the user off attempting a particular task. It can scare them off buying the product at all. As Bruce Tognzzini points out in his blog post, The Third User, Apple actually degrades the usability of its interfaces by hiding important controls in order to make their products look easier to use at first glance. The products are designed first and foremost to be purchased.
As anyone who has taught a complex task knows, people gain confidence with early success. As they go along, they not only gain confidence, they also gain commitment. A more complex problem that might have stopped them if they encountered it at the beginning of their quest, becomes something they can take in stride as their confidence and commitment grows.
Interestingly, this means that a product that is much more complex than it needs to be to do the task at hand, but which steps up the complexity gradually, may actually be more successful in the market than a fundamentally simpler product that requires its users to grasp its complexities up front.
(Nowhere is this pattern more evident than in content management systems where the safe and easy starting point of a WYSIWYG editing environment creates the need for vast amount of complexity down the road that could be avoided with a more structured editing interface that captures semantics up front. Almost all common tech comm tools have this pattern, with an easy on ramp, but a sting of complexity (and often fragility) in the tail.)
Of course, it is hard for the tech writer to control how far and how fast a user progresses, or to contrive situations that will give the user an early confidence-building success. My whole argument in Every Page is Page One is essentially that it is foolish to try to control the reader’s path, since the reader will follow their own course regardless. Still, even within an Every Page is Page One topic, there is room to step up the complexity level step by step rather than hitting the user over the head with it all at once. And by avoiding the TOC-in-your-face style of tri-pane help, there are ways to entice the reader into the docs without ever revealing their full scope or complexity.
The second caveat is that it is almost impossible for a person to grasp a complex idea simply by reading one document, however well crafted that document may be. This is because of what John Carroll called, “the paradox of sense making“.
A complex idea is essentially one that is at odds with the user’s current model of how the world works. (Even the most complex idea generally seems simple enough to those who understand it thoroughly.) But the user’s mental model of the world is far more real to them than what the document is telling them. They cannot integrate the new information and reset their mental model based on one document alone. They will have to experiment, make mistakes, seek advice, and possibly read several different sources before they can fully make sense of the new idea.
Minimalism was Carroll’s recommendation for the best way to accommodate the paradox of sense making. But Carroll was also very clear that minimalism was not a solution to the paradox of sense making. Carroll believed that no solution was possible. Learning is just hard and people have to go through their stumbles to really learn something new. Falling down is a part of learning to walk. A child who never falls will never run.
Minimalism is simply an approach to documentation that, compared to the systematic approach against which Carroll measured it, gets in the way of that learning less often, while assisting the user when required. Notably, unlike the systematic approach, minimalism does not attempt to keep the user on a single course dictated by the writer, but allows for the reader to depart, to experiment, to make mistakes, and to recover and learn from them.
You may not think minimalism is the best approach for your users or their circumstances. You may think you have come up with another approach that accommodates the paradox of sense making better than minimalism. (And you may be right.) But you cannot avoid the paradox itself, and if you ignore it, you do so at your peril and at the peril of your users.
To create content that best assists the user to act correctly in situations where the procedure and/or the consequences of an action are complex, merely documenting all of the complexity may not be the right answer. Simplifying isn’t the answer either, since to simplify would be to leave out essential information that the user needs to act correctly. But the approach you take to tacking the inherent complexity of the subject has to accommodate three inescapable facts:
- The user will not follow a prescribed path but will dive into the middle at the point that seems best to them according to their current mental model.
- The user may abandon the task if exposed to the full complexity all at once, before they have a chance to grow in confidence and commitment.
- The user will have to suffer through the pain of the paradox of sense making. You cannot make the paradox go away, you can only try to make the process less painful.