Part VI: Deepening documentation's value by simplifying complexity
- Complexity is relative
- Documentation that simplifies complexity
- Where do we find the bandwidth?
- Limiting your scope
Earlier in the essay (Part III), I argued that given the technical complexity of most products, they can’t be simplified such that documentation becomes unnecessary. However, just because documentation can’t be discarded, it doesn’t mean the documentation is still valuable. There’s a great deal of documentation that is simply terrible, including documentation that official “technical writers” create. Documentation may be necessary, so at some level, it provides “a value,” but that value might be so low that few people consider it valuable.
Think of the instructions that accompany your 1040EZ tax form. Necessary, but no one is thankful for the tax instructions, in part because they’re confusing and not really helpful.
The reality is that good documentation for complex systems is extremely difficult to create, and few possess the skills to do it well. The ability to translate complex information into simple, easy-to-understand language that most users (with varying contexts and skill levels) can understand and follow is more difficult than most people assume. To support my point, consider the following quotations about simplifying complexity:
“The definition of genius is taking the complex and making it simple.” — Albert Einstein
“Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius — and a lot of courage — to move in the opposite direction.” — E.F. Schumacher
“Simple can be harder than complex: You have to work hard to get your thinking clean to make it simple. But it’s worth it in the end because once you get there, you can move mountains.” — Steve Jobs
Either these assertions are just quirky, random things scientists and technologists say, or not. Presumably, scientists look for the simple laws (like f=ma or e=mc2) that underlie complex phenomena. Technical writers aren’t trying to discover the simple laws that govern the universe’s phenomena, but we are trying to distill simple explanations and steps from complex systems.
The effort doesn’t involve just grasping the complexity of a system; you have to simplify the information so that others can easily understand it. That second activity requires another level of intelligence. (If I were a master at this, my essay here would be one post instead of seven.)
Consider how hard it is when you have chaotic data, interconnected information, and other multi-faceted processes and details, and you have to sort through it all and reduce the chaos down to a simple expression — an expression (like a thesis) that renders the complex system clear in the minds of the reader, while not undermining its complex nature.
Simplifying complexity requires you to manipulate large amounts of information into patterns that are easy to follow, into an arrangement that makes sense when there isn’t any apparent order. You have to organize, reduce or expand, synthesize, and translate a lot of information into a form of knowledge that others can parse through.
The emphasis on complexity aligns with Peterson’s encouragement to tackle areas of complexity in order to reduce the stereotype that technical writers just make content look pretty (fixing grammar and formatting). By simplifying areas of complexity, we can re-align our role as driving value. Peterson says,
Because TPC [Technical and Professional Communication] as knowledge work is essential in the emerging economy of all-edge adhocracies, practitioners must engage in complex documentation and collaborative tasks.
As an example of such complexity, think about someone working on a Ph.D. dissertation and sorting through information from dozens of books, assessing the arguments and data, devising experiments to validate or dismiss ideas. Not only do technical writers gather and absorb large amounts of turbulent information, they have to distill it into a straightforward explanation or series of steps that leads users through a system or procedure. It’s not an easy task. This kind of higher-level mental processes is what you gain through advanced college degrees and scholarly study. Add to this challenge the difficulty of navigating within a specific programming language or framework.
We celebrate writers and presenters (like Bill Nye or Neil deGrasse Tyson or Isaac Asimov) who can make complex subjects in physics understandable. For highly complex topics, simplification is literally a skill that requires genius-level abilities. You have to understand the topic on a deep level, almost as a subject matter expert, yet still know how to write for the beginner (thus overcoming the curse of knowledge). You have to know how to select the details that matter, and then arrange them into a story that makes sense for the user’s journey and mental model. You have to communicate that complexity without jargon or specialized vocabulary, starting at a point where you don’t lose someone, but also engaging the audience at their level and using language that connects with their technical background.
As a profession, I think we underestimate the degree of difficulty required for simplification. In most cases, technical writers don’t possess the skill to simplify complexity in an impressive way. Adding subheadings and numbered steps helps make complex information easier to consume, for sure, but simplifying complexity gets more challenging as the subjects become more complex.
To provide the most value, technical writers shouldn’t merely gravitate towards documenting the obvious or easy features in a system. Instead, we should focus on the areas that are the most complicated for the users. That’s where we should live, swimming in that deep, turbulent ocean water where users are drowning.
To put it another way, tech writers should focus on string theory, not on directions to the corner store. (This assumes users struggle to understand string theory and already know where the corner store is.) Clearly, anyone who can explain string theory in a way that’s easy to understand will have value in an organization, without the need to continually justify his or her role.
This is where documentation has an opportunity to provide immediately apparent value. Have you ever used documentation and found that, for the areas that are highly complex (at least in your opinion), the technical writer glosses over the material? This is why Stack Overflow has been so popular — it focuses on these difficult, often fringe cases missing from docs. Stack Overflow answers the tough questions that technical writers often don’t attempt to wrestle. How much more valuable could documentation be if it focused on these areas of user complexity and made them easy to understand? Imagine docs written by Neil deGrasse Tyson or Bill Nye? In my mind, they would reduce the most complex part of a system into understandable prose that connects with users.
Complexity is relative
The challenge with simplifying complexity is that it’s not just a matter of identifying and focusing on areas of complexity without regard to users. It’s simplifying areas that users find complex. Complexity is in the eye of the beholder, so even something simple for the writer could be complex for the user. (As such, it’s probably more helpful to consider user “pain points” instead of complexity, but I’ve chosen to use the term “complexity” here because it aligns with the core value proposition of our profession, which is that we “communicate complex and technical information more easily” (according to the Bureau of Labor Statistics).
Because complexity is relative, it’s even harder to handle because you no longer have a clear measure of whether something is complex. Here’s an example. Last weekend I visited the Cantor Museum with my wife and two youngest children. On the second floor, there was an activity station for children:
The idea is to fold a piece of paper in a right way as to create a mini-book. The station is intended for little children who get bored by the exhibits and need a more hands-on activity. Great, we just fold some paper in a defined pattern to make a book, right? Sounds simple. Here are the instructions:
Although it seems easy, it turned out to be quite complicated for the user, which in this case is my 7-year-old, who needed Mom to explain it. In contrast, my 11-year-old found it easy and did not need help.
Consider the same scenario with the iPhone. For the digital native, few instructions are needed. But for senior citizens like my Dad or others who didn’t grow up installing apps on smartphones, it can be quite complex when something goes wrong. In fact, even understanding the difference between cellular network data and wifi network data is somewhat beyond the folks in his assisted living center. About half the people don’t even know their network wifi password in these places (I’m not kidding). He is constantly frustrated that his iPhone doesn’t seem to have any instructions that put information in clear, understandable English.
Which scenario is more complex? The 7-year-old trying to understand a Fold-a-Book? The senior trying to connect to a wifi network when he can’t remember his password? Or explaining string theory to someone who already has a background in physics? I’m not sure, but you can’t just use yourself as a measure for what is complex. “Complexity” is entirely relative. What’s complex to one is simple to another. What’s simple to one is complex to another. Since you’re trapped by your own context (and technical level, background, and perspective), you can only play guessing games about whether something is complex. How do you even recognize when a subject is complex if it seems intuitive to you? What if it seems complex to you, but turns out to be common knowledge for the developer users? How do you write for multiple audience levels without duplicating writing efforts?
It’s natural to use ourselves as the measure for complexity. If we can follow the instructions and concepts, we assume our audience will as well, but that often turns out to be false. You can’t actually know whether something is complex to users without having access to those users! This is yet again another argument that, in order to tackle complexity, we have to interact with other groups (Field Engineer, Support) that interact with users to even identify the areas of complexity.
My larger point here is that complexity has multiple dimensions and depth and is not an easy solution. It is more complex to simplify these Fold-a-Book instructions for a 7-year-old than it might be to explain string theory to a physicist. If we merely resort to information mechanisms that would make sense to other adults, we haven’t found a way to transmit the information to the 7-year-old brain and make the child’s neural synapses light up with understanding. Just how do you do that? It’s a complex undertaking. It’s like teaching a dog to shake, or teaching a parakeet a limerick. Finding the right teaching model to connect with the user is the complex part, not the topic itself.
Documentation that simplifies complexity
In another essay, I’d like to dive into principles we can use to simplify complexity. But in brief, the kind of documentation that simplifies complexity and has immediate, obvious value might have characteristics like this:
- A natural organization to the content that makes sense according to the user’s journey and mental model
- An at-a-glance presentation of all parts that make up the system, giving users the big picture
- The ability to easily zoom out for the big picture, or zoom in for more details
- A Google-like search that returns results users want
- Workflow maps that pull users through a complex process step by step, even with branching scenarios
- Visuals such as concept diagrams and workflows that simplify complex ideas
- Short videos to show processes or techniques in dynamic ways
- Glossaries and glossary tooltips over jargon or other specialized vocabulary
- Quick start guides formatted in attractive ways that users can print
- Hello world tutorials that get users up and running in a beginning-to-end way
- Plain language principles to keep language short, readable, and straightforward
- Iteratively tested content with target audiences, improved over time
Where do we find the bandwidth?
To produce documentation that simplifies complexity for a range of users, it might take 3-4 times longer than a quick write-up of a procedure. Given the ever-increasing workloads technical writers face, how can we get support for the required time? Are we forced into sub-par outputs because of quick deadlines (e.g., two weeks before product launch) and onerous product loads (five projects at a time)?
Even if you were to invest the necessary time to bring documentation’s grade from a C+ to an A, organizations would still undervalue the content. The reason comes back to Hughes’ point about the unconscious incompetence of the product teams. Most engineers and product managers don’t realize the complexity of their products. They are unaware of their own proficiency and understanding of a topic, so a technical writer who goes to great pains to make these concepts and techniques even more simple and clear isn’t going to receive widespread praise and recognition.
In an engineers’ mind, technical writers expend a lot of energy documenting information that is somewhat obvious and shouldn’t need so much detail. How many times have you heard engineers say, “If users don’t understand this, they shouldn’t be using the product.” In their minds, the users are supposed to already have a certain level of knowledge as a prerequisite. That presumed knowledge (which is an easy way to dismiss usability issues) is what will make the product seem simple to the user.
Because this tacit knowledge (unconscious competence) abounds in the workplace, both mediocre documentation and outstanding documentation will probably have the same perceived value to the organization. The only solution is for technical writers to assess and argue the documentation’s value in context of the users rather than in the context of other internal product teams.
Limiting your scope
A question about scope remains. Should you continue to try to juggle 5 projects and produce poor, hurried documentation for all of them, meeting the release deadlines as required by your project load? If you do, you end up devaluing documentation even more, because the output (which likely won’t simplify complexity) will only confirm preconceptions about the low value of documentation. You’re not given time to produce outstanding documentation, so documentation is poor and has little value. Because documentation has little value, fewer technical writers are hired to create this low-value resource. With fewer technical writers, the project loads increase, and technical writers must churn out material faster, perhaps resigning themselves as editors, publishers, and curators rather than knowledge creators — this leads to even lower value documentation. The cycle feeds on itself. Technical writers become the “information packagers” that Hughes wrote about. They confirm perceptions that Peterson warned about in regards to secretarial labor, where technical writers only make documents pretty.
On the other hand, suppose you were to push back on your project scope and limit yourself to 1-2 projects only, but you deliver documentation that has strong value. Your documentation takes complexity and makes it simple for users to understand and follow. Perhaps you can make a case based on this value to hire more writers. But how do you get the authority to push back on the project loads? The question is not easy to answer, and perhaps I haven’t fully addressed some of the questions I set out to answer, which include how to persuade senior leaders of your value. But if you can make a case for value, using some of these strategies I explored earlier, perhaps you can start to move the organization in the right direction.
About 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.