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.)

Great Last-Minute Gifts for Communicators

In keeping with our long-standing (OK, we started it last year) BTL tradition, it’s time for the annual last-minute holiday gift guide for online shoppers. It’s Monday, December 21, and Christmas is THIS FRIDAY

So, here are links to several sites offering a random assortment of uncommon gifts for the really deserving technical communicators who are still on your list…the ones who are so hard to buy for. Here you go!

• STC’s Amazon affiliate link for books your writer friends will love. And your purchase makes a little gift of its own to the STC coffers.
• MoleskineUS (mol-a-skeen’-a US) for your journaling friends who can appreciate the “legendary notebook of artists, writers, intellectuals and travelers… [possessing] stylish minimalism and unmatched quality. “
• A subscription to Premium Crosswords from New York Times for your puzzle-loving friends (like me, for example. You might also want to stuff this friend’s stocking with a helpful order of erasable pens.)
• The definitive reference for technical writers, editors, and documentation managers, Read Me First! A Style Guide for the Computer Industry, Third Edition, is an award-winning style guide written by senior editors at Sun Microsystems. Read Me First! has been revised and updated to cover everything from creating screencasts and referencing web sites to writing for wikis. (Unfortunately, this edition will not be published until after the holidays, so this amazing gift will have to be a pre-paid, redeemable card from Amazon. I’ve already ordered mine!)
• Shakespeare’s Den , an online store full of “gifts for intelligent people,” including your as-yet ungifted writing friends.

Rush-shipping orders placed with most of these vendors by noon on Monday, December 22, can be expected to reach their destination before Christmas. {Non-retail items require a little more ingenuity.)

Happy last-minute shopping!

Have you ever been absolutely amazed by a sentence? Like this one …

Herein lurk delegitimized power structures and epistemological straitjackets and stuff.Duncan Stevens

…or…

CRP, an enhancement to BRP, allows the company to manage the performance of critical enterprise applications end-to-end globally and optimize the performance dynamically across any network according to user criticality and bandwidth allocation.

Amazing sentences were the topic when SWO Member and STC Associate Fellow Sylvia Miller reminded me of the annual Bulwer-Lytton Fiction Contest (BLFC).  BLFC, described at www.bulwer-lytton.com (where www stands for Wretched Writers Welcome) is a whimsical literary competition that challenges entrants to compose the opening sentence to the worst of all possible novels. Sylvia also noted:

I’ll bet all of us could nominate some good “worst possible sentences”–just not opening sentences of novels!

Sylvia and all of us put our sanity on the line every day; we wrestle with ugly, incomprehensible, and stupefying sentences in the line of duty. So, BTL is sponsoring a Tortured Technical Communicators Competition (TTCC) just for people like us, with the following rules:

• An entry consists of a single sentence submitted via the Comments section on this page. (You may submit as many entries as ;you wish.
• Sentences may be of any length, but must be amazing examples of obfuscation, misdirection, non-communication, and passive-aggressive jargon-speak alleged to be technical communication.
• The official deadline is November 30.
• All incomprehensible and confusing entries received will be published in the December issue of Between the Lines.
• The grand prize winner will be determined by the BTL editor (that’s me) and will win an amazingly incomprehensible prize to be announced in the December issue.

So share some of your incredible examples of horrific technical communication. You never know what you might win!

by Judith Harper

Do you write procedures? Then always KISS and TELL; your readers will love you. Let me explain.

Every halfway decent tech writer understands how and why to KISS — Keep It Short and Simple– but not as many are willing to TELL: Test Every Line for Logic. Writing procedures is, after all, an exercise in clear communication, not an exhaustive process definition.

So here’s how you KISS your readers and TELL them the safest and most efficient way to accomplish a task.

Use the Six Keys

Make sure that you’ve covered the six W’s: Who, When, Why, What Conditions, What Steps, and What Followup.

But that’s just the beginning.

Analyze the Steps

Reversing the proverbial KISS and TELL order, now it’s time to Test Every Line for Logic by analyzing the sequence of steps. Procedures, by their very nature, have to be sequential, and not just any old sequence will do, because:

• If your procedures backtrack or omit critical steps, they’re no better than trial-and-error.
• If your procedures provide “oh, by the way” safety warnings that follow risky operations instead of preemptive warnings that precede the hazardous steps, they’re not just inefficient–they’re dangerous.

To provide instructions that make a logical progression:

1. Make sure you have determined the end goal(s).
   A complex procedure has a grand destination, or end goal, that is the culmination of lots of smaller subprocedures, each of which has its own end goal. For example, a novice cook whose end goal is yummy potato salad actually has several subgoals.
   • Get the potatoes ready (scrub them, cook them peel them, cube them)
   • Prep the eggs (boil them, cool them, peel them, chop them)
   • Put together the dressing (measure and mix mayonnaise, mustard, spices)
2. Account for required conditions.
   Things that the reader must know about, tools he must locate, schedules to be followed–all these things are part of the logical analysis. Describe each required condition at the right place in the procedure–before the user begins the step where the condition becomes significant.

Cut Out the Fat

After you cover who/where/why/what/what/what and test the logical progression of your procedures, it’s time to KISS and break up clumps of unnecessary words, useless modifiers, and superfluous explanation. One of the most effective ways to cut unnecessary words from your procedures is to use pictures.

I once worked with an extremely intelligent woman for whom English is a second language. She always listened carefully to instructions and followed them closely, but sometimes had a difficult time with some of the language used to outline the steps. When she understood what was being conveyed, she always said emphatically: I got a picture!

Include whatever it takes — diagrams, photographs, graphs, charts, line drawings, screenshots — to give your readers a picture of what must or must not happen in the procedure–without squandering words.

Remember — your reader counts on you to guide her safely and efficiently to the successful completion of her task.

Keys to Effective Editing

by Margaret VanWinkle

Tech writers document processes, organize procedures, and pay great attention to detail. One of their often-unacknowledged activities is editing. In an attempt to strengthen my technical writing skills, I recently completed an online course from www.ed2go.com entitled “The Keys to Effective Editing”.

The instructor stated that the primary responsibility of an editor is to clarify the author’s words and intent. An editor doesn’t create additional material; an editor doesn’t insert words into the author’s mouth. A good editor does leave an author feeling that the document is still the same document, only better written.

The six-week course provided instruction in editing both fiction and non-fiction.

Course topics applying only to fiction included an introduction to copyright law and to front and back matter (content at the front and back of books). Fiction editing itself is quite different from editing technical documents. Tracking character identities and story lines would be interesting, but it requires a definite change in mindset from the typical work of editing facts and layout in a technical document.

Several topics, applicable to both fiction and non-fiction, were especially relevant to technical writing:

• Copy editor symbols (both handwritten symbols and Microsoft Word’s Track Changes)
• Techniques for better syntax and style, such as avoiding stereotyping and sexism (for example, “if the customer calls about his/her/their purchase”)
• Using active vs. passive voice
• Using parallel construction
• Guidelines for spelling, capitalization, number usage, abbreviations, and hyphens
• Common grammar and punctuation problems

I found the lesson on how to build and maintain good editor-author-publisher relationships surprisingly practical. Although technical writers do not customarily work with authors or publishers, we often work with project managers. In both cases content must be agreed upon, deadlines must be met, and personality differences must be overcome.

One lesson was devoted to illustrations such as artwork, photographs, and tables. The instructor provided rules for numbering items and labeling contents. She also demonstrated how to track these types of illustrations, especially if content is rearranged. It was also interesting to note that, although an editor seldom reviews table contents, it is prudent to confirm that formula results are correct.

The instructor emphasized the need for consistency and included an extensive list of style guides. She also illustrated clearly how to use a style sheet. Creating one for my department’s use resulted in a lively discussion regarding personal preference and consistency in presentation.

The final lesson provided information on beginning an editing career. Considering the number of tech writers who are facing employment challenges, this last topic itself may be worth the course cost in order to learn how to expand one’s technical writing skills to a related field.