Simplifying complexity
Overview
Ask a technical writer what they do, and the most common response is that tech writers “simplify complexity.” In systems that are complex (supporting many tasks, options, functions, and information), we figure out user goals and create clear instructions on how users can achieve those goals. The technical writer’s core value is in his or her ability to simplify information in these complex systems.
But for all the talk about simplifying complexity, there’s not a lot written on how to do it. Just how do you make complex processes and concepts easy to follow? How do you help users achieve their goals in the context of sophisticated, confusing applications and code? Explaining concepts in plain language and using task-based steps is a great start, but it’s not the entire solution. We need to increase our skill at this game. Technical writers need to center on what’s complex for users, and use all the tools available to turn up the simplicity factor in ways that add real value to organizations.
I’m fascinated by the idea that my core value as a technical writer involves helping users make sense of complex systems. We should center our efforts around the user’s greatest pain, because that is where we can deliver the greatest value — and that is also where the space is the most interesting. We don’t deliver value by documenting simple, obvious instructions, or by providing instructions for interfaces and workflows that are already well-designed and intuitive. We deliver value by first identifying what users struggle with most, their point of utmost complexity and frustration, and then set our sights on that maelstrom and sail directly towards it.
Ways we simplify complexity
As a profession, I think we need more focus on ways to simplify complexity. In this series of essays, I’ll outline a number of techniques and approaches for simplifying complexity. Some of these techniques might involve embedding journey maps that carry users through a process from beginning to end. Other approaches might involve providing high-level summaries that distill and crystalize key points from large swaths of information, condensing it into quick reference guides. An approach for simplifying complexity might include tagging content with the right metadata to be surfaced when the user needs it. Or consuming the entirety of the information space to see just how the piece we’re adding integrates and harmonizes with the whole. It might involve looking beyond our product to consider the larger journey our users are on – even before they arrived at our product. Or shaping our documentation around schemas the user already uses to categorize information. Or implementing interactive JavaScript to hide complexity for the majority of users who don’t need the information.
The task of simplifying complexity is even more difficult in the landscape of developer and API documentation. Developers have deeper, more comprehensive technical skills and understanding than most technical writers. And yet, even so, technical writers can still simplify information in ways that become vital to the developer’s success. Of course, simplifying complexity involves understanding enough of the domain and customer journey to speak at their level and in their terminology, but it’s more than that. Simplifying complexity involves incorporating a host of techniques that go beyond mere transmission of knowledge in a particular domain.
My hope is that by understanding the right techniques and approaches, we can do our jobs better. We can provide more value in our roles. As we simplify complexity in deep ways, we can move beyond merely being perceived as editors, writers, or publishers. We become knowledge creators and usability experts in information spaces.
My approach
I will approach this topic similar to my API documentation site. That is, I’ll add to it continually over a period of months and years, constantly refining it and developing the content based on continued feedback, thoughts, research, and experiments.
To get started, you can read the topics in any order, as they are self-contained and not sequential. One of my favorites is the first topic: Switching between macro and micro views with embedded maps. I welcome your feedback and insights.
Who am I?
I’m currently a senior technical writer Amazon in Sunnyvale, California. I’m best known for my blog https://idratherbewriting.com, where I post regularly on tech comm topics and have one of the largest followings of technical communicators online. Additionally, I’ve created an extensive web API documentation course that has helped hundreds of technical writers transition into API documentation.
Lately I’ve been working on a series of essays around Simplifying Complexity — published on this site — because I believe this topic is core to increasing value in our discipline. I have given more than 100 presentations over the past decade at various tech comm events. I’m always open to trying new things, and I enjoy exploring and discussing ways to innovate in the tech comm space. Feel free to contact me with any questions or thoughts.
Tom Johnson
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.