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 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.
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.
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.
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.
You can take other approaches to unraveling complexity as well:
What’s your approach to decoding complexity?
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.