Bill Blondeau
This article is the first in a series. The series is a practical overview of the best ways to get good-quality technical writing done.
This is largely a distillation of years' worth of work doing technical documentation of various sorts. However, a lot of it was founded on an an excellent book, Analytical Writing, by Thomas P. Johnson (Harper & Row, 1966). Unfortunately, the book's out of print.
I was also recently pleased to acquire a copy of Anne E. Greene's book Writing Science in Plain English (University of Chicago Press, 2013). Greene reinforces a lot of the precepts in Analytical Writing, and adds a lot of complementary insights, especially as applied to scientific writing and the extremely poor literary conventions imposed upon the academic world of science.
This is an introductory article. It lays out the subject in a bare-bones fashion. There's
This article is big enough without detail diving. Subsequent articles will unpack the list items, and any supporting topics that deserve a fuller discussion. These descendant articles will be forward and backward linked.
So far:
...So, let's get right to it.
There's no more important guideline in technical writing than this: technical writing is entirely about conveying information to the reader.
Which sounds... kind of obvious?
Sadly, considerable evidence indicates otherwise. There's a lot of terrible, awful, no-good scientific and technical writing out there; and it's bad in a way that suggests that this "one job" gets less attention than it should.
This article assumes that you don't want to add to the problem. It offers advice to keep you out of trouble.
The first and most important piece of advice is to really accept the guideline above: You are here to inform the reader. Everything else follows from that.
You inform the reader by giving her well-organized information in a way that fosters clear and accurate understanding, while requiring the lowest reasonable effort on her part.
She's interested in understanding the material—that's why she's reading your article, book, or whatever in the first place. She doesn't want to burn up her time and attention just to make scant, laborious progress through your written work.
You owe her a fair chance.
You should be very much focused on reaching the reader: not emotionally, not even intellectually really, but cognitively. You're in the business of conveying information that the reader can assemble, in her thought, into useful and accurate structures of understanding.
That's it. That's all you're doing.
Compose and write for the reader's understanding, and for nothing else. If you can buckle down and truly do this, you'll be way ahead of the pack.
I mentioned establishing a "cognitive" connection with the reader? There's one key concept for understanding the difference between getting that right and getting it wrong.
Cognitive burden, in expository writing, is a measure of how much mental effort the reader has to exert in order to grasp the material you are writing about. It's related to "cognitive load", a more formal term from cognitive psychology. I won't recapitulate the psychology now—the links are there, if you want to dig in—but the core practical insight we can draw from cognitive load, and apply to technical writing, is this:
As a technical writer, you're describing an immutable information set.
As a technical writer, always focus on the second bullet: changing the things that are in your territory.
Cognitive burden can arise in almost any part of your work.
You may screw up the analysis, misidentifying key concepts, or misunderstanding them. You may fail to organize the material clearly. You may construct jumbled or unfinished explanations.
Your prose might be awkward, distracting, filled with garbage. You may write paragraphs longer than William Faulkner, in full stream-of-consciousness mode, ever did. You may overuse abstractions. You may be a serial prepositioner. You may simply suck at writing sentences that help the reader stay with you, in the frame, in the picture.
You need to learn to avoid these things, to notice them when they happen, and to know how to repair them. Aside from actual misinformation, cognitive burden is the worst thing you will ever impose on the reader. Doublecheck yourself. Work hard on recognizing and correcting cognitive burden.
It says something unhappy about the field of technical writing that the level of cognitive burden is characteristically pretty high.
There are lots of things that you can do to help the reader grasp the material without undue effort. These are the ones that matter the most. This list is hopefully short enough, and simple enough, that it can lodge in your memory.
(Remember, though: simple doesn't mean easy. There's work here.)
This is the "Always Helpful, Never Wrong" list of writing practices. The more fully you can apply these, the better your technical writing will be.
Abstractions are incredibly powerful and helpful for analysis and synthesis, but they are usually insufficient for introductory explanations. Give concrete, explicit examples before exploring the abstractions they illustrate. You won't be sorry.
There are some common, deeply unfortunate, poorly founded behaviors that technical writers often exhibit. Usually these writers mean well, and think they're doing the right thing. They are not. These things result in bad work.
This is often a difficult issue, because it's (at least partly) rooted in social conformity. Even worse, it's often driven by insecurity on the part of technically-adept people: they aren't confident in their verbal skills, so they support bad writing as a norm.
In some scientific and technical communities and organizations, awful terrible no-good writing is, in fact, expected and conventional. Sometimes, it's demanded outright. Your best response is to do a better job without bowing to the pressure to write badly, and see if it's acceptable. Sometimes you can move that needle.
(And, even if your article or paper is rejected for insufficient obfuscation, you have the benefit of having completed a superior draft. Save it separately, disfigure the next draft to order, and move on.)
Check yourself—your natural style, and your individual drafts. Wherever, whenever, you find instances of the following failures, fix them. Then, work on not doing it in future.
Note that this is even worse in scientific papers, generally, than in tech writing.
And in a couple of weeks, you won't either.
When you're thinking, "I don't have to explain that!" you're making a very common, and very destructive, blunder, based on a temporary cognitive state: when your head's in the game, you underestimate the game's difficulty. And you neglect the precursors of reason and information that got you there.
Write for when your head is not in the game. And write for the user whose head never was.
They will be oriented, because the material is now attached to something they already know.
They will be gratified. Possibly even smug. Smug is good in a reader. Smug means that they are more than willing to pay close attention to the rest of the things you say.
The two foregoing lists are the core practices that this article advocates. If all you do is write the bold text on your hand with a ballpoint pen, you will be better off than you were.
So, Dear Writer, there you have it.
There are many other things you can, and should, do if you want to be a good and honorable technical writer. But if you start out by following the principles and practices sketched out here, you'll be treating your readers a lot better than if you don't.
Stay tuned for further installments.