How can technical writers cut through engineering jargon and decode complex information?
- A typical tech comm scenario
- The technical writer’s first task
- Approaches for tackling complexity
- Step one: Break it into small pieces
- Step two: Be an investigative reporter
- Other ways to unravel complexity
A typical tech comm scenario
The other day I was asked to update documentation for the latest release. The team pointed me to some internal wiki pages that described the new features and work of the sprint. As I looked through the pages, they were full of engineering speak as thick as it gets, with Java methods, acronyms, almost no explanation of the context or “why” behind the feature, and other technical blah blah blah.
After 5 minutes, I browsed to another tab and looked for something else to do. I didn’t want to deal with figuring all of that out right then. Soon I came back to the jargon-filled wiki page, and this time read it more slowly. This time I started to take notes, pulling out the essential information.
It still looked like gobbley gook. When engineers write, they seem to revel in making things as cryptic as possible, so only they can understand what they’ve written. Maybe to them it seems as clear and succinct as possible. To them…
The technical writer’s first task
The technical writer’s task, more or less, is to decode complexity. We take something incredibly dense and difficult to decipher, and little by little we unravel it. We decode the tech into natural, understandable, readable language.
Approaches for tackling complexity
Given that we set about unraveling against complexity all day, what are our methods for figuring complexity out for ourselves? I constantly hear about how tech writers simplify complicated ideas and processes into simple, readable speech. But I never really hear how technical writers go about decoding and unraveling the complexity in the first place.
Here are the strategies I follow.
Step one: Break it into small pieces
To decode the indecipherable engineering speak on the wiki page I mentioned, I decided to break the content into small pieces. I took it one section at a time, one paragraph at a time, one sentence at a time. When I understood the first sentence / paragraph, I wrote an outline of points in my own words, and then moved on to the next.
This is the first step to unraveling complexity. Taken as a whole, it can be immense and impenetrable. So you take a little piece of it and own that piece. Define the acronyms, understand the concepts, figure out the code.
Then you take another piece, and another piece, and so on.
Step two: Be an investigative reporter
Much of the information on the wiki page had a surrounding context that wasn’t on the page. Engineers had discussed these features and fixes in meetings – meetings I hadn’t always been in (and frankly, which I really didn’t want to attend). Sprint planning, special issues, backend coding decisions, and such.
I set about asking engineers around me for information. Every time I talked to an engineer, I would get a firehose of useful information that would help me understand what was going on.
Fortunately, I sit right next to all the engineers — 5 feet from the project manager, actually. I say Hey Fred (not his real name), what does X mean. And he explains it to me. I walk over to Jane (not her real name) and ask what this code does, and she explains it to me.
I return to my desk and make more notes, slowly putting together the information and transforming them into coherent documentation.
Other ways to unravel complexity
You can take other approaches to unraveling complexity as well:
- Draw a picture. Nothing makes things come into focus like a diagram or illustration. (Unfortunately, I don’t do this enough.) Dan Roam emphasizes this strategy repeatedly in Blah Blah Blah: What to Do When Works Won’t Work.
- Experiment on your own. This is one of the best approaches — stepping through the task yourself. Unfortunately, the more complex something is, the less accessible it is to reproduce (oh, just create a Java app on an embedded Jetty server instance and emulate traffic from mobile devices you don’t have from countries you’re not in and determine whether the generated 40-character-hexadecimal identifier is the same 80% of the time…).
- Rest your brain. Sometimes when I can’t figure something out, I sleep on it. In the morning, the answer comes to me. Or basically if I just take a break, the problem keeps churning in the backburner of my mind and eventually simmers with an answer.
What’s your approach to decoding complexity?
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.