by Ben Kauffman (reprinted with permission)
In this wired, impatient world, our careers may depend on the ability to deliver minimalist documentation. The benefits are threefold: better readability, lower translation and printing costs, and easier reuse.
A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.
—William Strunk, Jr.
In the Beginning
Perhaps the first bit of technical documentation on record was a short life manual called the “Ten Commandments.” It was so simple and easy to read that many folks still follow it today. “You shall not commit adultery.” Nothing flowery. Second person imperative, active voice—good solid writing.
Over two thousand years later, we need to remember those simple lessons of straightforward language, and return to minimalist documentation. In this wired, impatient world, our careers may depend on it. The benefits are threefold: better readability, lower translation and printing costs, and easier reuse.
As consumers, we despise instructions. With little time and less patience, we ignore directions and warnings as we size up and unpack and attempt to install our new home improvement purchases. “It’s not rocket science,” we say, ever hopefully. And perhaps this is true—if your new product is a toaster. But much of what you and I document is rocket science. It is difficult to understand, and that is why we are paid well to do it.
Unfortunately, our customers are no more excited to read our documentation than you and I are to read up on how to plug in a toaster. And our customers are sometimes right not to be excited.
What good, for instance, is a 500-page field service manual that is too ungainly for a service technician to carry in the field? As much as novels and films must be edited, so too must documentation. Part of our problem lies with the fact that, as William Strunk, Jr. writes, “A common way to fall into wordiness is to present a single complex idea, step by step . . . ” (Strunk 24). Of course, that’s exactly what we do every day—so we have to be extra vigilant.
Further, we default toward over-writing due to the amount of time we have invested in each manual, painstakingly translating engineer-speak. Perhaps we’re proud of our work, and want to give the reader more bang for their buck. But remember, customers spend their bucks on the product, not the documentation, and any time spent reading documentation is time spent not using the product.
Writers and editors alike must do more than simply proofread, and check grammar and readability (i.e. Does this make sense?), we have to answer the reader’s questions as quickly as possible.
We understand, in the world of fiction writing for instance, that it may require writing three pages to whittle down one good one. It’s silly to think tech writing is so different from “regular” writing to the point where every word is necessary. Writers must be more judicious, and edit themselves. If they are unable to do so, then editors must.
Faulkner v. Hemingway
Let’s take the argument out of the realm of technical documentation for a moment, and grossly oversimplify. There are two types of writers. The first type of writer is William Faulkner.
Faulkner writes beautiful flowing lovely lilting prose. Adores words. The more the better, and the more flowery the better. Sentences become paragraphs become pages. If Faulkner had been paid by the word, he might have written only one book.
Consider the following passage from the beginning of Faulkner’s Absalom, Absalom:
From a little after two o’clock until almost sundown of the long still hot weary dead September afternoon they sat in what Miss Coldfield still called the office because her father had called it that—a dim hot airless room with the blinds all closed and fastened for forty-three summers because when she was a girl someone had believed that light and moving air carried heat and that dark was always cooler, and which (as the sun shone fuller and fuller on that side of the house) became latticed with yellow slashes full of dust motes which Quentin thought of as being flecks of the dead old dried paint itself blown inward from the scaling blinds as wind might have blown them. There was a wisteria vine blooming for the second time that summer on a wooden trellis before one window, into which sparrows came now and then in random gusts, making a dry vivid dusty sound before going away: and opposite Quentin, Miss Coldfield in the eternal black which she had worn for forty-three years now, whether for sister, father or nothusband none knew, sitting so bolt upright in the straight hard chair that was so tall for her that her legs hung straight and rigid as if she had iron shinbones and ankles, clear of the floor with that air of impotent and static rage like children’s feet, and talking in that grim
haggard amazed voice until at last listening would renege and hearing-sense self-confound and the longdead object of her impotent yet ndomitable frustration would appear, as though by outraged recapitulation evoked, quiet inattentive and harmless, out of the biding and dreamy and victorious dust (Faulkner 1).
This is epic southern fiction, yes; unfortunately, no one gets paid by the word to read it. You may even have seen the block quote coming, and skipped right over it. I don’t blame you. In fact, if you did skip it, you’ve proven my point—readers don’t like to read.
We have more patience when hearing someone tell a story than when reading it. Cut to the chase, we say. That leads us to the next type of writer—Ernest Hemingway. Hemingway gives us just the facts. The man was tired. The boy was excited. The tuna was enormous. Beautiful documentation.
That said, let’s take another look at Faulkner’s passage, above. But let’s give Hemingway’s ghost the power to edit Faulkner. No more adjectives; Hemingway, like a good movie director, would focus on the action, and shred the section to its absolute core: “They sat in the office. Opposite Quentin, Miss Coldfield sat, talking.” We lose the back-story, yes, and some development of themes, but in terms of technical writing, the edited version is obviously much better.
Hemingway was nothing if not discerning. He knew what to leave out. Or as George Orwell wrote in his essay “Politics of the English Language,” “If it is possible to cut a word out, always cut it out” (Orwell 383). To which I would respond, “If it is possible to cut a word, cut it.”
The Benefits
Minimalist documentation is certainly more user-friendly, but there are more tangible benefits as well, like cutting printing costs. On-demand techniques such as docutech and direct-to-plate printing can help lower costs, and being able to deliver PDF or HTML files can save you bundles, but the bottom line if you have to ship hard copy is that you pay for pages. Fewer pages equals lower costs.
The most palpable savings, though, are in translation costs, which can run anywhere from thirty to forty cents per word. Cutting words, phrases, sentences, sections can add up to big money. I used to work for a company that was required to translate user manuals to all eleven European Union languages, plus Japanese. Because of this, I often performed what our translators then called a “volume reduction edit,” in which I strived to cut the text by 15 to 25%. In terms of a 350-page user manual, our savings on translations for one volume reduction edit alone could equal a dollar figure close to my yearly salary—an argument that can easily justify a raise, come performance review time.
So, how to start? With an eye toward efficient, minimalist documentation, edit from large scale to small:
- Cut unnecessary introductory sections, and sections that review self-evident features. Often, just a glance through the table of contents can help you quickly identify some of these problem spots.
- Use simple, concise wording. Don’t write two sentences to explain something you should be able to explain in one.
- Cut empty words and phrases like “there are.” Instead of “There are three steps to installing the system,” use “Install the system as follows.” And change “Install the diskette that is labeled Disc 1” to “Install the diskette labeled Disc 1,” or better yet, “Install Disc 1.”
One caveat: never sacrifice clarity for brevity. Generally, you can achieve both, but just as the writer’s first thought is not always the best, nor is the editor’s, and so it takes time.
Back in 1946, Orwell could see that writing “consists less and less of words chosen for . . . their meaning, and more and more of phrases tacked together like the sections of a prefabricated hen-house” (Orwell 375). Documentation is all about meaning, and so we must force ourselves not to settle on the first, often prefab, words that pop into our heads, but to uncover the best words.
In addition to saving on translation, the benefits of minimalism extend to reuse. As our documentation becomes “content,” and technology reduces that content to the size of one’s palm, we need to choose our words more carefully. We shouldn’t burn our Faulkner, and documentation should not become Gregg shorthand, but clearly, shorter is better.
So keep it simple. Put yourself in the reader’s shoes, and do the front-end work necessary to save everyone time and money. Remember the- um- eleventh commandment: You shall not commit verbosity.
(Ben Kauffman is Technical Publications Manager at Cadence Design Systems.)