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 design of tri-pane help rubs the reader’s nose in the complexity of the documentation set — which implies a similar complexity in the product.
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.
Analecta Communications can help you develop an effective approach to tackling this challenge. Contact us today to see how we can help.
Mark
This was a tremendous discussion that not only highlights the problem, but also explains the factors that led to our company becoming involved in applying Expert Systems technology to the Customer Support/Tech Services world. With complicated products and processes, you always have to ask yourself “how would the expert solve the problem?” Dumbing down the description of effective, albeit complex, diagnostic and service protocols does not help. Furthermore, overly simplified content becomes lethal for non-expert users when it is posted blindly to knowledge bases in the form of dozens of partial “simple” articles so that searches for the optimal procedure are drowned out by unhelpful results… albeit results that contain highly relevant keywords.
Expert system software is finally emerging as a unique platform that can properly and efficiently capture complicated procedures and then structure delivery to the user in linked steps which are individually simple and can be correlated in real-time to related background information. The technology allows the experts to model how they would pose questions to diagnose issues and then, based on the answers, structure responses to all the different outcomes or diagnostic pathways that are so challenging for traditional knowledge management approaches to accommodate. The user simply answers questions and is guided by the system to the correct diagnosis and suggested resolution.
It should also be pointed out that the emergence of predictive diagnostics and structured machine-based learning has solved the traditional negative to expert systems, which was its requirement for significant setup and maintenance effort on the part of the experts. This can now be more efficiently automated. Having the platform available as a cloud service has also really changed the calculations for justifying expert decision support. I’d love to see a thread on your site on the role of expert system technology from the tech writing perspective. Thanks for a great discussion.
Thanks for the comment, Patrick.
The question with an expert system approach is always, can you get people to use it. But that is a subject for another post.
Mark, you make some good points – especially about having to accommodate the paradox of sense making. A couple of observations:
You say that the term “usable” and “transform” (in STC’s mission statement) suggest that we want the user to perform a task of comprehension. I disagree. If anything, the word “usable” implies using a product, in other words taking correct action. (If we wanted to talk about comprehension we’d use the word “understandable.”) And while I appreciate your disliking the concept of transformation, I don’t think it implies anything about the kind of action we want the user to take.
Second, you can get users to follow a prescribed path – but first you have to earn their trust. This requires many successful interactions with the user over a span of time. Once the user’s trust is earned, you can recommend a path and expect that some users will follow it. You’ll never get all users to follow it, of course, so you can’t forsake the EPPO principles. But you’ll have an opportunity to use new content formats, like tutorials, that wouldn’t otherwise be available to you.
Finally, when you say “correct” action, who gets to define correctness? I think that you’d say the user defines correctness, in which case I agree with you. But I fear that someone reading this might infer that our goal as writers is to get users to do what we want them to. Only in the broadest sense (I want them to use the product as effectively as possible) is that true.
Thanks for the comment, Larry.
Implication is a tricky thing. Statements that are similar to many other statements tend to get tarred with the same brush, even when they are saying something subtly different. Tom points out the subtle difference. I react to the substantial similarity. To be clear, I was not saying that the STC statement had these implications specifically, but that the whole class of “transformation” based definitions has these implications.
I’m not satisfied with a mild departure; I want a radical disavowal of the transform/translate model. I think this is necessary, because when people hear a familiar phrase, they tend to automatically file it with all the other instances of that phrase, and all the associations they have with all those phrases. (We can see this clearly in political discussion where people tend to assign people to one party platform or another wholesale.) A subtle change in wording is not enough to prevent a phrase being filed with the rest. You need a much stronger differentiation.
Fundamentally, my objection to the transform/translate model is that it devalues the profession. What the public hears in this definition is “make the words pretty”, which they class at about the same level of difficulty and importance as making the formatting pretty. What we need to win any kind of public respect for technical communication is to portray technical writers as experts in their field who create original content to make technology easier to use.
(I don’t, by the way, necessarily agree that “usable documentation” implies using a product. Many tech writers seem to infer that this means nice binding, lots of white space, and a good index — things that can make a book more usable as a book but have nothing to do with making the product more usable.)
I will agree that you can earn the reader’s trust under the conditions you describe. The question is, how often do those conditions apply? I think we have to be very clear about what it takes to create those conditions, and not simply assume (as we often did in the past) that those conditions exist a priori. The default today is Google. To win people over to a separate default for our particular product is a very difficult challenge (on which more when I get around to the planned post on expert systems).
On the last point, however, I can’t agree. Technical communication is a commercial activity and commercial activity is often about trying to get people to behave in the way you want them to. If you are being paid by a vendor, then it is part of your job to support your employer’s business goals. Despite their distaste for marketing, technical writers need to accept the unavoidable fact that everyone who has any interaction with the customer is in marketing, and is responsible for meeting marketing’s goals.
For example, on two different occasions I have worked for companies who sold low-level tools for software developers. In both cases, the vendors were trying to get their customer to buy and use their IDE rather than use their tools at the command line, so they go increase revenue from their IDE sales. Most of the developers who used the products, however, preferred to use their own editors.
Both companies wanted the documentation to encourage the reader to use the IDE rather than the command line. My job as the writer of the documentation was to encourage that change in behavior. As an employee, it was my obligation to do so. And since there is noting morally objectionable about encouraging people to use an IDE, that’s what I tried to do.
Most of the time, of course, we are helping the user act correctly by their definition of correctly. Sometimes we are urging them to act correctly by our employer’s definition of correctly. As long as there is nothing illegal or immoral about the behavior we are trying to encourage, there is nothing wrong with that.
In fact,we communicate with other people in an attempt to change their behavior all the time. Pretty much everything ever communicated in politics aims at this goal, for instance. Deceit and extortion are wrong; persuasion is not.
“Despite their distaste for marketing, technical writers need to accept the unavoidable fact that everyone who has any interaction with the customer is in marketing…”
Yes, absolutely.
“….and is responsible for meeting marketing’s goals.”
Yes, if Marketing’s goals are truly aligned with the overall goals of the business. They usually are so aligned, as you’ve pointed out. But if Marketing has an outmoded goal, like forcing customers and prospects through a “sales funnel,” then we’re on a fool’s errand. Isn’t it a fundamental principle of “Every Page Is Page One” that every reader will access our content in the way they choose, and that we can’t choose that way for them?
Excellent point, Larry. Every Page is Page One is a message the marketing needs to hear every bit as much as tech comm. So if marketing is, as you say, still trying to force every reader through a sales funnel, there is nothing to be gained by tech comm following the same model.
That said, of course, an holistic content strategy should lead to a coordination of message, approach, and even architecture between marketing and tech comm. In many organizations marketing is oblivious to what tech comm is doing, and vice versa. It shouldn’t be that way. So ideally marketing and tech comm should be working together under a common content strategy umbrella the makes sure they are both aligned with business goals, and hopefully using an approach that is realistic about how people actually consume content today.
And on that score, Mark, you and I are in complete agreement.
I really can’t agree with the both of you on this. Reality shows us, that we (marketing and tech comm) are facing a common enemy which is bad product design. Our only common business goal on that fact is, to cover the awful design in our very own ways. Marketing needs to do the sales and its weapons on this are to lie, mislead and misinform. Tech comm does the opposite. We try to fix the bad design by writing “796 simple steps to reach your goal”. We try to disguise the bad design and the lies marketing used to get the customers on the hook.
What you are insisting on, is to do things right with a product. But as long as Marketing, Tech comm, Product Designers and engineers don’t work together from the moment the idea for a new product is born, the above mentioned will inevitably happen.
Alex
Pingback: The Goal of Tech Comm is to Enable Correct Acti...
Pingback: Tech Writer This Week for April 10, 2014 | TechWhirl
Pingback: Passive vs. imperative linking | Every Page is Page One