Search results

An argument for complexity rather than simplicity in technical communication

by Tom Johnson on Feb 7, 2014
categories: technical-writing

I am rarely impressed by mission statements, but I find the first paragraph of the recent reformulation of STC's mission statement refreshing. It defines the practice of technical communication as "the discipline of transforming complex information into usable content for products, processes, and services" (President's Midterm Report).

The mission statement does continue on to address other less interesting topics, but that's beyond my concern. Instead I'm drawn to the phrase "transforming complex information into usable content." Does this describe the profession of technical writing, i.e., what you and I do?

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.

Sometimes when talking about the practice of "simplifying complexity," technical writers mean they translate engineering jargon into plain speech that the audience can understand. Rather than creating "simple concepts" or "simple tasks" out of complex processes and complex information, technical writers merely massage the words and format their shape into something more readable.

But the lines between simple language and simple concepts and tasks is blurry. If a concept or task is incredibly complicated, but the writer has communicated the complexity with perfect clarity, has the writer simplified complexity or merely made the complex information "usable"?

Are you starting to see the difficulty here? Separating language from concepts and tasks isn't a "simple" distinction.

Rather than "simple," I like the word "usable," as the STC mission statement declares. We are involved in the UX of information, a trade parallel to other user experience professionals but focusing on information -- or is it "content"? Does information that has been made usable earn the title of "content," as the mission statement puts it? That transformation from "information" to "content" is an interesting shift, one that suggests either the writer looked for a synonym to avoid redundancy (the discipline of transforming complex information into usable information...") or the writer believes "information" differs from "content," though the distinction isn't defined (so much for simple language).

Here's why I dislike the idea of simplification. All too often, product managers want to communicate that their product is simple to use. They like short, brief instructions that resemble what you might expect from a simple-to-use product.

Yet any technical writer knows that once you get into the business of figuring out how something works, it turns out to be a lot more complicated than surface appearances seem. When you get into the nitty-gritty details of configuring, setting up, executing, etc., you find all kinds of gotchas, quirks, notes, exceptions, warts, and other ugly details that, once documented, makes the product seem more complicated than simple.

As a technical writer, do you make the product more simple? Or do you raise awareness of just how complicated the product really is?

Let's take a step back and look across disciplines for a moment. Philosophers and scientists have been asking whether the underlying world is simple or complex for centuries. Is there a fundamentally simple formula that everything derives from, something astonishingly basic? Is everything a repeating pattern (like a fractal is a repeating pattern) which reveals an underlying simplicity to our world? Or do we live in a really complex world with many variables, random actions, multifaceted interactions, and other confusing and nearly impossible-to-predict details driving it all?

See what I'm getting at when I have second thoughts about the phrase "simplify complexity"?

Here are a few quotes from writers that give more context to the argument for complexity:

“I never knew anybody . . . who found life simple. I think a life or a time looks simple when you leave out the details.”

― Ursula K. Le Guin, The Birthday of the World and Other Stories

“The ideal art, the noblest of art: working with the complexities of life, refusing to simplify, to 'overcome' doubt.”
― Joyce Carol Oates, The Journal of Joyce Carol Oates: 1973-1982

“Abandon the urge to simplify everything, to look for formulas and easy answers, and to begin to think multidimensionally, to glory in the mystery and paradoxes of life, not to be dismayed by the multitude of causes and consequences that are inherent in each experience -- to appreciate the fact that life is complex.”
― M. Scott Peck

Rather than champion simplicity, these writers celebrate complexity in all its wonderful detail.

Photo from Flickr
Photo from Flickr

To further clarify why I value complexity, let me relate an example. I recently purchased a pair of Waterfi waterproof headphones (so I can listen to audio books on my waterproof iPod while I swim). On the third lap, the left earbud's volume nearly faded entirely. I wrote the company asking for a refund. Their support team sent me some tips on fixing the issue:

I am sorry that you are having problems with your waterproof headphones! The good news is that your headphones are still under warranty.

Also there are some troubleshooting steps you can try as due to pressure on the waterproof membrane, sometimes the speakers can get stuck. This is usually caused by a sharp change in altitude, such as air travel, and will equalize naturally. If it's been a few days and there is no change, there are a few troubleshooting tips that should clear this issue right up:

Plug the headphones into an audio source and play it loud enough that you will be able to hear if the speakers start to work again.

Now, try tapping the ear buds on the palm of your hand with the speaker hole facing down and try to create suction when you pull up on the ear bud. We are trying to release the speaker inside that might be stuck due to air pressure.

If that fails to create a change in sound, bang it on your palm a few times and then test once more.

Next, try blowing in then sucking out the air in the ear plug. We are trying to flex the internal membrane in both directions. Test again.

If none of these tips works, set the headphones aside and allow them to play at about 90% volume for several hours (2-4 hrs). You don't need to be there for this period.

Having sound fade out with waterproof headphones is a pretty common problem. The same thing happened with two other pairs of waterproof headphones I own. So why doesn't Waterfi post their tap-bang-suck-blow troubleshooting steps in the documentation for their headphones? No doubt because it makes their product look crappy and complicated to troubleshoot. Instead, the company would have you believe that the product "just works," as people often say.

But if it doesn't "just work," if I should expect the internal membrane to periodically stick to the earbud wall, requiring me to tap, bang, suck, and blow on the earbud now and then, then I am ready to embrace this truth. I do not want simple explanations for what is actually a more complex process.

Note again that the troubleshooting information/content from Waterfi is fairly simple to understand. That is probably what a lot of technical writers mean when they say they "simplify complex information." Their simplification is really a translation of the complexity into human readable language, not a simplification of the complexity of the ideas or tasks.

What is not simple, however, is troubleshooting the earbuds. You have to tap it just right, bang it on your palm or the desk (how hard, and at what angle?), suck in the side (which side and how long?), and blow as well (how hard are we talking about blowing here?).

When complex is better than simple

As I have been arguing, sometimes complexity is better than simplicity. I recently rewrote a "Getting Started" tutorial at my work. The previous version of the tutorial used a different technology that we were mostly retiring. The new technology is much more flexible, open, and admittedly, more complicated. The Getting Started tutorial has quite a few code samples and requires users to have a decent understanding of JavaScript to use the product. Gone are the days of blindly copying and pasting code snippets to get what you need.

Rather than downplay the complexity of the product, I didn't hide the complexity. Not backing down helps qualify the audience from the start. Imagine someone who purchases a product with the thought that it's easy to use. Perhaps the user reads an unhealthy dose of marketing literature and decides to jump in with full confidence. Once the user gets into the nuts and bolts of the product, however, the user realizes that he or she lacks the skills to configure and actually use the product.

Such is the case with self-hosted WordPress sites. Web hosting companies make it drop-dead simple to install WordPress in your own web host space. WordPress itself opens up the source files for you to freely alter, edit, and update. But unless you know HTML, CSS, PHP, and WordPress template tags and hierarchy, you're likely to get in over your head quickly if you start trying to customize a theme or alter the default functionality. Yet unless you plan to make some customizations, there's little argument for using self-hosted WordPress ( instead of the freely hosted (which isn't customizable beyond stylesheet alterations).

One way to avoid traps where inexperienced users get themselves in trouble is to make WordPress more difficult to install. If your installation process sets the bar at a certain knowledge requirement (such as creating the database through phpmyadmin instead of "Simple Scripts"), you reduce the likelihood that unskilled users desiring a "simple" solution will end up lost and stuck.

Moving from simple to complex, or complex to simple

I once heard a comic artist describe his role as follows. He said, My job is to afflict the comfortable and comfort the afflicted.

I feel the same way about information. Where information is simple, I will show you its underlying complexity. Where information is complex, I will show you its underlying simplicity.

Why is this such an appealing philosophy? I'm not sure. I hope it's more than a contrarian gene in me.

Most of the time, in tech comm contexts, we do move from complex to ... "usable," as the STC puts it. But the academic mindset is usually just the opposite. The academic's job is often to open up the complexity where no one else sees it.

I love how philosophically minded people can take a relatively common idea and show us much more than is on the surface. Literature professors do this routinely as they raise discussions about texts. Putting on their critical theory glasses, they look at the subject from constructionist, deconstructionist, historical, feminist, narratological, rhetorical, moral, racial, poetic, and other views. They bring to our consciousness all the complexity behind a seemingly simple text.

As a graduate student teaching composition, I once bet students we could occupy an entire hour discussing something seemingly trivial, as long as we just asked the right questions. A student picked up a walnut shell off the ground and said "Okay, discuss this." We proceeded to talk about whether feeding the many squirrels on campus, which were fed by students using just such walnuts, was ethical or not -- for both the university and the squirrels. (Of all the composition classes I taught, this was my most memorable.)

One problem with opening up complexity behind seemingly simple topics is that it frequently gets you into institutional trouble. Institutions of every stripe -- religious, political, and social -- tend to bind members together through a set of common principles and beliefs. As soon as you start questioning them, raising issues and problems that open them up, and show the ugly (or beautiful) complexity, you begin to unravel the ideology that tends to make the group cohere. Institutions do not do well in moving from simplicty to complexity. Instead, they often specialize in the opposite movement.

Simplicity as champion

A few years ago I listened to David Pogue give a keynote at the STC Summit. His theme was basically to celebrate simplicity and praise products designed with ease of use; in contrast, he made fun of complicated, hard-to-use products.

If given the choice, I can't imagine anyone would choose a complicated product over a simple one. Hence simplicity has become the most powerful selling point for many technology products. Even as companies add feature after feature to their products to stay competitive, they must also continue to proclaim that their product is simple to set up and easy to use.

Technical writers usually become caught up in this simplicity bandwagon. Deliver a 500 topic help system for an application that has just a few screens, or 150 topics for an API that has fewer than a dozen methods, and you've suddenly violated the whole momentum and flow of the simplicity movement. No product can be simple and easy to use if it has a 500 page reference manual, right?

But dumbing down a manual to its core features can have just the opposite effect. Without the right information, the product becomes more challenging to use. Anyone who has tried to use the dial on an iPod Nano knows that while the circular wheel looks simple, there are a lot of unknowns one has to discover in order to learn how "simple" the product is.

And I'm not just talking about products here. Any process or subject tends to be the same way. Less information is not always "more," as people like to spin it. When my Waterfi headphones faded, was it advantageous to me not to have information about how to tap, bang, and suck the earbuds to bring them back to life (tips which, I must add, did not actually work).

The trick is to not to remove information, but to remember that the reader is an emotional being. Large amounts of information are intimidating because they suggest massive time commitments, which the user doesn't want to give. Therefore the technical writer must hide information until the user wants it. The technical writer can use progressive information disclosure and other strategies for hiding endless lists of information. For example, rather than putting everything into a massive, all-encompassing table of contents (TOC), you can break up information into a variety of smaller TOCs.

At the same time, I'm not suggesting that documentation should be infinite or that all edge cases should be documented. I'm saying that products and their related documentation should not be portrayed as being simple and easy to use when they are not. Technical writers should be truth-tellers, with a respect for the complexity of information. Certainly we communicate in a human readable way, using lists, numbered steps, subheadings, visuals, examples, and other tools to communicate ideas. These techniques make the language usable. But we don't betray the complexity of the products or processes by supposing that they are simple or that the concepts, tasks, and processes for using them can be made simple.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.