Blogroll Language Process Training Uncategorized Water Cooler Stuff Writing

Technically Speaking by Eric Sedor

Technically speaking, technical writing is writing, but all writing is not technical. Consult the textbooks and you’ll find much material describing the difference. Consider, however, the possibility that technical writing is not writing at all.  Compare, say, Moby Dick to your latest furniture assembly instructions:

Consider the subtleness of the sea; how its most dreaded creatures glide under water, unapparent for the most part, and treacherously hidden beneath the loveliest tints of azure.


Insert dowel (A) into hole (B) and secure with Allen wrench (C) (included).

When viewed as writing, one of these is a veritable “See Spot run” of literary runoff, omitting everything about the somber mass grave that awaits the quixotic Allen wrench in the back of some unused tool drawer with unnumbered others of its race. The other drips verbosity from that first ironically laconic statement “Call me Ishmael”, and is so dense as to bludgeon most children into never reading or writing again.

When you compare the two, even the most technical of technical writing seems dry and uninteresting. And that’s saying a lot because Moby Dick is more often called “arduous” than “gripping” but certainly, forgive the pun, never dry.

What does this comparison mean?

Well, even though it takes a skilled writer to condense a lot of meaning into those small, unadorned sentences so useful for instruction, this means that there are skills other than writing involved. That’s obvious, you say, and cleverly note that technical skills are involved. But what kind of skills? The answer is that no one really knows, which is why the terms “technical aptitude,” “technically-minded,” and “tech-savvy” get so much play in the hiring space. In such a precise space, these terms are curiously literary, don’t you think?

If you could boil all that literary flamboyance down into one definitive kernel, what would it be? Here’s a proposal:

Writing technically about a subject requires the ability to transcribe that which has no meaning without knowing anything about it.

“that which has no meaning”

You can read Moby Dick and learn a great deal about all manners of things without any foreknowledge, like whaling in the 19th century. However, a furniture assembly manual – in a vast majority of circumstances – is relatively irrelevant. It will be useful once to assemble a specific model of furniture by a specific manufacturer, and, even if you are addicted to furniture, the usefulness of the manual fades once you set the Allen wrench down. In the grand scheme of “classic literature” that has withstood the test of time, the furniture manual is excruciatingly novel and ultimately disposable – the  exact opposite of classic.

“without knowing anything about it”

Outlining a story is one thing. Outlining a process is another. However, both share consistency and logic requirements. That which comes first should not contradict that which comes last. An author, like a technical writer, often writes segments “out of order” relative to the final product. This is more difficult for technical writers because generally the “story” they are writing doesn’t come from the writer at all. Unless the technical writer is employed in very specific circumstances, the chances are that the technical writer doesn’t even have direct access to the “story.” Ultimately, this leads a technical writer to rely on placeholders to give meaning to a predetermined “story.”

Consider the following case: A technical writer and an author are in a conference room and the technical writer is interviewing the author for a piece on the writing process. The author says “First I do a mind map, then I outline, then I write, then I edit.”

A poor technical writer’s first question – assuming he hasn’t picked up the knowledge from somewhere – is “What’s a mind map?” A decent technical writer’s first question is “Does the mind-thingy only inform the outline or does it inform writing and editing as well?”

A good technical writer doesn’t have any questions yet. He doesn’t need to know anything about those four things (mind map, outline, etc.) to put them in a list, slap headings on the sections they link to, and fill in the rest later. A good technical writer can google “mind map” and doesn’t waste time derailing a subject-matter expert’s flow of thought on the subject he’s documenting.

Even though authors may write out of order, this is not generally their primary mode.

Good technical writers can learn as they go. They recognize that a vast majority of our lives are governed by symbols, and that these symbols are interchangeable to a great extent. As “symbologists” they are perfectly comfortable doing something “tech-savvy” like variable substitution. They use “****MIND-THINGY****” in their document until the document coalesces around the section, and, like a spider finishing a web, they connect the last dots when it is truly necessary and appropriate.

So, next time you’re interviewing a technical writer, grab your best document and turn one of its important sections into gobbledygook (for the non-technical among you: Select all text in section. Press delete. Type “gobbledygook”). Put the document in front of him/her and ask him/her what happens in that section. I call this the Queequeg test. If he “see him spot and pretend him one whale eye,” you’ve got a proven crew-member.

With (slightly) less metaphor: To the extent that the candidate is able to use surrounding information to infer accurate meaning of the blemished section, he’s the one to hire. You have found a writer fit to hunt the white whale of reliable technical documentation.

Leave a Reply

Your email address will not be published. Required fields are marked *