3 Principles of Technical Writing
An annotated guide to simplifying technical writing for a nontechnical audience.
So far, I have focused on articulating the “why?” and “what” parts of strategic writing. Why this choice instead of that? What specific consumer segment are we interested in?
But now I will look at the “how” part through technical writing.
By technical writing, I do not mean documents with API code or spec sheets on datasets.
While these are types of technical writing, there are other examples that we see that are highly specialized and help us see the “how” of our work:
Details about a new product design.
The methodology and results of a pilot program.
Onboarding materials on how you run a digital media campaign.
Technical writing is intimidating, though — and for good reasons. First, it’s labor intensive and can be tedious. Second, it’s often hard to translate our jargon into plain sentences. Third, it can sometimes show us the limits of our knowledge about our subject.
Nonetheless it is vital genre in our workplace canon.
And poor technical writing can hold your company back.
People share documents around. The deck you sent to a client may get forwarded to ten other people who will have varying degrees of knowledge about your topic. Unfortunately, insider terminology, specific acronyms, and underlying assumptions are stumbling blocks for outsiders – namely, the people outside of your team, department, or company. Consequently, your writing is more punishing than productive.
Our goal, therefore, should be to write accessibly without those trappings so that both the experts and lay people can understand us.
To do so requires clear thinking and simple writing skills, balancing the right level of detail, selecting the right words, and placing them in the right order.
Here are 3 guiding principles that will help you improve your technical writing:
Assume people don’t know why your topic is important.
Explain everything in simple terms, avoiding jargon and defining technical words.
Be sequential and don’t skip over your reasoning or assumptions.
In this post, we are going to look at each of these principles through two examples from Anna Blaustein, a writer for Scientific American, and Robin George Andrews from The New York Times. I picked these articles because, as all good journalism does, they apply all three for mass audiences.
1. Why This Is Important:
Academics like Drs. Adam Grant and Emily Oster take research, meta-analyses, and other data-rich sources and explain them to a mainstream audience in digestible ways. It may seem mysterious how they are able to write specialized information so plainly.
But they do so by not assuming the audience knows the ins-and-outs of their particular subject.
William Zinsser, author of On Writing Well, explains this approach:
Imagine science writing as an upside-down pyramid. Start at the bottom with the one fact a reader must know before he can learn any more. The second sentence broadens what was stated first, making the pyramid wider, and the third sentence broadens the second, so that you can gradually move beyond fact into significance and speculation—how a new discovery alters what was known, what new avenues of research it might open, where the research might be applied… Your readers will understand the broad implications only if they start with one narrow fact.
Balancing what to include and what to exclude is crucial. There are known facts that are common to the expert, but you may need to outline them for a lay person. Without proper orientation, the lay person may get lost.
As Zinsser recommends, you should start with one simple fact and build out from there.
Let’s look at an example by Robin George Andrews from the New York Times about a recent discovery NASA made:
From star-destroying black holes to exploding comets, NASA’s Transiting Exoplanet Survey Satellite, or TESS, has spotted its share of surprises since it began searching the galaxy for exoplanets in 2018. But the source of starlight that was mysteriously brightening and dimming some 1,900 light-years away may top all those discoveries for its science fiction-like grandeur.
Commentary: This opening sets up the “so what?” of this discovery in a way that people outside the space community would understand. By starting with this one fact, Andrews now moves into “significance and speculation”:
The source, named TIC 168789840, is a system of six stars. That alone makes it a rarity, but what makes this sextuplet even more remarkable is that they consist of three pairs of binary stars: three different stellar couplets revolving around three different centers of mass, but with the trio remaining gravitationally bound to one another and circling the galactic center as a single star system. Although a handful of other six-star systems have been discovered, this one is unique: It is the first in which the stars within each of those three pairings pass in front of and behind each other, eclipsing the other member of its stellar dance troupe, at least from our space telescope’s line of sight.
Commentary: The writer goes on to explain what this discovery is: binary stars. He also explains how this is unique (what they found is different from others).
When you are writing for a broader audience, each detail you include must serve a purpose and you must make it known why you are including it.
2. In Simple Terms:
In the second and third section, we are going to use one example. This is from Anna Blaustein’s article in Scientific American on how octopuses experience pain.
Scientific research can be very technical and include a lot of highly specialized language, so it can be impenetrable for the layperson.
Take a look at the words used in the title of the original study and its summary:
Noxious stimulus
Location-specific grooming
Affective pain
Neurophysiological
These are the appropriate words for people in the field, but they are difficult for mass audiences. Unless you study biology for a living, you would probably need to Google each of these.
Blaustein deftly translates these concepts for us in her article.
In this piece, Blaustein starts by explaining why the experiment is important:
It is [the] emotional aspect of pain that is relevant for animal welfare, ethicists say. But it is difficult to measure. “I don't think there’s any way of proving that another organism, even another human, actually, is experiencing conscious pain the way that we ourselves do,” says Terry Walters, a pain researcher at McGovern Medical School at the University of Texas Health Science Center at Houston, who gave feedback for an early draft of the study but was not directly involved.
Commentary: In this opening, we learn why they’re doing the experiment (this is an ethical concern for animal welfare) and what the central issue they are trying to solve (measuring pain).
How do you measure pain, though? Blaustein then goes on to explain how they did it:
The closest we can get for other species, [Walters] says, is determining what situations and experiences they try to avoid. That is what Robyn Crook did using a so-called conditioned place preference test at her lab at San Francisco State University. This test is a common method of determining whether mice and rats are experiencing pain, and she found that octopuses behave like their mammalian counterparts in the assay.
Commentary: Not only do we learn how scientists measure pain in non-humans, but we also learn the term for this test (“conditioned place preference test”). Moreover, we learn why this test was chosen: it is a common method in this practice.
The goal is not to avoid specialized words, but instead to use simple language to explain the technical so that the reader does not stumble over the significance of what you’re saying.
3. In A Sequential Order:
Here is the final component where we lay the building blocks of our pyramid.
“Nowhere else must you work so hard to write sentences that form a linear sequence,” Zinsser writes. “This is no place for fanciful leaps or implied truths. Fact and deduction are the ruling family.”
Laying out a process or a method sequentially not only helps us understand how we got to the conclusion, it also can reveal any gaps.
When I was getting my MBA, I was a research assistant for Dr. Whitler. We published a study in the MIT Sloan Management Review about poorly designed C-Suite job specifications. In scientific and academic research, writing out your research methodology opens the door for people to not only understand what you did and how you reached our conclusion, but also it gives an opportunity for people to see any potential flaws in your approach and to contribute ways to make it better.
The same is true for summarizing any design tests, product pilots, user research.
Stories are more useful here than a simple bullet point list of what you did. But more importantly, you need to explain your subject in order.
Returning to Blaustein’s piece, she narrates how the researchers conducted the pain experiment:
During the experiment, Crook placed a Bock’s pygmy octopus between two chambers, one with stripes on the walls and the other with spots. Both patterns were new to the animal and intended to catch her attention. The researcher then let her roam around and observed where she lingered.
The next day, in another part of the lab, Crook injected a small bead of acetic acid into one of the octopus’s arms. She says doing so is like squirting lemon juice on a paper cut. When the animal awoke with a stinging arm, Crook confined her to whichever chamber she had preferred before.
The researcher removed the octopus 20 minutes later and administered lidocaine to numb her arm. Crook then placed her in the chamber she had not liked as much at first. After another 20 minutes, Crook returned her to her home tank.
Finally, about five hours later, Crook brought the octopus back to the chambers and gave her a choice: return to the initially preferred chamber, where she was confined with a stinging arm, or go to the one she had not liked as much but where she was numb. “All we’re asking is, ‘What do you remember feeling in those two places?’” Crook says. She ran the experiment with seven octopuses. They consistently chose to go to the second, nonpreferred chamber. As a control, Crook injected seven other animals with saline instead of acetic acid. Unlike the experimental group, those octopuses returned to the room they had originally preferred.
Commentary: She shows step by step what is happening. The process unfolds like a story with key narrative words and phrases that signalled progression (“During”, “The next day”, “Crook then placed her…”, etc.) It also brings to life what is meant by the “conditioned place preference” and exactly how the octopuses came to avoid one place.
Blaustein then summarizes the results, helping the audience to see how the researchers got there:
The results show the cephalopods’ complex pain experiences. They associated the chamber they had once liked best with the stinging they felt the last time they were there, even though the injection occurred somewhere else. Then they compared that experience with their typical pain-free state and decided that how they usually felt was better. “That’s the sort of big cognitive leap you have to make to be able to do this particular learning experiment,” Crook says. Using all that information, the octopuses chose to go to the nonpreferred chamber. “There’s a lot of conscious processing that has to happen,” she says.
Commentary: In this piece, Blaustein hits the key points economically. It only took her 251 words to describe how the research was done and 100 words to describe the results.
If you’re worried about how long it would take to write about your work, you can surprise yourself when you force yourself to be succinct!
When you are writing anything that requires specialized knowledge, remember that you should go in order step by step, describe it in simple terms, and say why it is important.
This is a skill that takes time to build, but it will help you be a better communicator and help your audience learn your point of view.
Here is William Zinsser again:
For the principle of scientific and technical writing applies to all nonfiction writing. It’s the principle of leading readers who know nothing, step by step, to a grasp of subjects they didn’t think they had an aptitude for or were afraid they were too dumb to understand.
Try these exercises:
Start to build an operations manual for your role: take one core thing you do regularly and lay out step by step what you do. Explain why each step matters and clear up any jargony words in there.
Describe a pilot, test, or research you’ve done: what were the steps you took to reach your conclusion. Ask someone to read it and share their feedback.
Thanks for reading.
Stephen
What are the most challenging parts of explaining the specifics of your job to a lay person (your friend, your spouse, or a colleage in another department)?