We Don’t Do Tech Writing Like This Any More

rogersgeorge on September 20th, 2017

Here’s a sentence from some correspondence from the 1700’s:

Your Majesty’s Ministers, persevering in their measures, and proceeding to open hostilities for enforcing them, have compelled us to arm in our own defence, and have engaged us in a controversy so peculiarly abhorrent to the affections of your still faithful Colonists, that when we consider whom we must oppose in this contest, and if it continues, what may be the consequences, our own particular misfortunes are accounted by us only as parts of our distress.

It’s from a document called “The Olive Branch Petition,” addressed to King George III (but delivered to the Earl of Dartmouth) not long before the revolutionary war, written by Richard Penn and Arthur Lee, representing the Continental Congress. The king wouldn’t even read it, but not because of the complexity of the sentence, I suspect.

Here’s an exercise for you: Rewrite that sentence in today’s English. You can make more than one sentence out of it, and I recommend you do.

PS—I just realized that this is my 500th post! As my brother would say, Hoo-ah!

Subscribe to this blog's RSS feed

Technical Writing

rogersgeorge on July 1st, 2016

This blog is about expository writing—explaining things—but a headhunter technical recruiter recently asked me what a technical writer does, and my answer was the germ for this post. Technical writing is a subset of expository writing, but it’s a pretty large field. Here are my thoughts on the subject.

Technical writing consists of four main writing-related activities; two main ones, and two more generic activities.

Writing instructions. This, I think, is what most people think of when they think of tech writing. The readership is people who don’t know how to do something, want to be able to do it. I tell people it’s “Put tab A into slot B.” It typically looks like a paragraph telling what’s to be accomplished, then a set of steps, numbered, with an illustration for each step. Repeat as necessary. You generally see a cover page of some kind, maybe a table of contents, and sometimes some sort of reference (appendix) in the back. When you write instructions, get someone to follow them! Watch them make mistakes. The mistakes show what’s wrong with the instructions. Fix the instructions.

Describing progress. The main readership of this material is colleagues and people who are checking up on what’s going on; managers, auditors, regulators. I suspect more tech writing is this activity than any other. Projects, especially large ones, especially software development, especially when someone is checking up on things, are the arena for this part of tech writing. Even a project as small as building a deck on the back of the house uses this kind of documentation. You need a description of the deck, a bid from the contractor, plans, a bill of materials, and the invoice. Those are all technical documents. Build a bridge, rocket, or office building, and you have those documents in spades. The description becomes specifications or requirements, for example. In the financial industry, banks have to create descriptions of several stages of their software development projects, partly to convince auditors and regulators that the bank is being responsible in the handling of customers’ money. Even the regulations are technical documents. These descriptive documents have to describe everything. Think detailed lists of requirements, records of meetings where people decided what to do,  detailed lists of tests, reports of the test results, reports of reviews of the computer code to demonstrate there’s nothing malicious in there, the list goes on and on.  Most of these documents aren’t very glamorous, but they can be important. What if the tech writer had been careless describing the contents of the Apollo 13 space capsule? They used that information to figure out a way to scrub carbon dioxide out of the air, saving the lives of the entire crew!

Helping marketers. I think I’ve said before that tech writers regard all marketing people as insane. But technical things need to be sold, too, and described both convincingly and accurately. White papers, proposals, grant applications are all documents whose purpose is to sell something, and they need to be accurate. Tech writing is the part that makes sure that brochure is telling the truth.

Editing and proofreading. Over the years I’ve checked restaurant menus, résumés, newsletters, ads, brochures, even kids’ reports for school. Many people are careless or unskilled about the mechanics of the language, and the wise get someone to look over their work. Tech writing is helping people not look dumb.

Maybe you’re a tech writer reading this. Did I leave anything out?

Interesting use of “technical writer”

rogersgeorge on November 29th, 2013

A recent article in The Register criticized Google’s Eric Schmidt for, among other things, his (lack of) ability as a technical writer. Since this blog is mainly about expository writing, of which technical writing is a subset, I feel a need to share. Here’s the passage I’m referring to:

…Schmidt goes on to show he’s not conversant with the gentle art of technical writing with procedures that use inconsistent verbs, fail to open each step of a procedure with an active verb and make assumptions that lead to user-befuddling ambiguities.

Gentle art, eh? I’m flattered. Eric’s instructions are too long to quote here (you can find a link them in the article), but the criticisms mentioned in the quote above are worth noting for your own writing.

Inconsistent verbs…active verb. I’m not sure what the writer is referring to here, but when you write instructions, you should use the imperative. Do not say “Please.” Give one instruction per step. Tell the result of following the instruction correctly. (Do not write the result as a separate step!)

User-befuddling ambiguities. Ambiguity is the bane of technical writing. You should write so your material is interpreted exactly one way. Have someone follow your instructions. If they get something wrong, fix the writing. Do not whack the person upside the head for being stupid.

Tech writing has a lot more features, and I saw several other tech writing mistakes in Eric’s material, but I won’t go into them here.

Now in Eric’s defense, he is not a technical writer. He’s an extremely successful businessman with lots of money. (Warning: shameless plug ahead) If his intent is to write a good set of instructions (and not a marketing piece disguised as tech writing) maybe he should hire (ahem) a good technical writer to write the instructions for him.

Google's Eric Schmidt

Eric Schmidt. Image credit: AP

Metaphor in technical writing

rogersgeorge on February 22nd, 2012

In the most general sense, a figure of speech is when you do something artistic with your writing. You’re probably familiar with alliteration and onomatopoeia, but how about synecdoche? (Look it up. You use it.)

I generally recommend a writing style that doesn’t call attention to the writing itself, so conspicuous figures of speech are generally not a good idea. The less technical your writing is, the more you can get away with using figures of speech. They add color and interest to the writing; make it a little more fun to read.

Metaphor is a figure of speech that compares two things by saying that one thing is the other. A post a while back contained a lot of metaphors. You learn about metaphor in grade school, usually with its cousin, the simile, which compares to things by saying that one thing is like the other. (“My love is like a red, red rose…”)

Normally you won’t find it a good idea to use metaphors in technical writing. You should stick to the literal truth, the plain facts. Metaphors can confuse the issue but bringing in extraneous concepts. Recently I read a book that was on a technical subject, but it was addressed to a lay readership, and the introduction was the perfect place for the author to use a couple of metaphors to make his description of his subject more vivid. The book is about anthrozoology, the study of how humans relate with animals. The title of the book is Some we Love, Some we Hate, and Some we Eat. It’s a pretty interesting read, and you can click the link to go to Amazon to get it. Here are the metaphors:

“How much money are you giving out?” I ask. Two and a half million dollars a year, she says. “Fantastic! This is just what the field needs,” I say. I am thinking that Layla is going to have a very full dance card for the next couple of days.

Anthrozoology is a big tent. It includes the study of nearly all aspects of out interactions with other species.

As academic disciplines go, anthrozoology is a small pond, but in the last two decades, we have come a long way.

Those quotes contain four metaphors. Can you find them all? The fourth one is so common you might not notice it.

I try to find an excuse to put up pictures, so here’s what the cover looks like:

Sorry about the arrow; Amazon will be Amazon.

A nice example of substitution

rogersgeorge on July 16th, 2011

A couple posts back I wrote about the two most basic verbs in English, pointing out that some form of “do” can replace any action verb. I also said that you should avoid using the verb do itself, but here’s an example of using it that’s okay.

Our quote today, class, is from the July 2011 issue of Scientific American. This issue is particularly interesting to me—it’s the first issue I recall having a centerfold, and it’s hanging on the wall in my room. (Don’t get your hopes up, guys. It’s a poster of the Hertzsprung-Russell diagram (look it up), which turns 100 this year.)

Back to grammar. We find our quote on page 55 near the bottom:

It will be an uphill battle in a country that reveres an individual’s right to choose much more than it does science.

The verbs in the parallel construction are “reveres” and “does.” You can get up in front of the room and revere (something). This is approximately what cheerleaders do at a high school pep rally. And you can replace “does” with “reveres,” which makes the sentence end with “…than it reveres science.”  Go back and read the sentence with “reveres” in there both times. That’s exactly what the sentence is saying.

Why did the writer (Sharon Begley, a top-notch science writer) not use the more specific verb in the second part of the parallelism? In English we usually consider it poor form to repeat a word. Repeating something exactly without enough distance between the repeated words feels patronizing. The writer didn’t want to patronize her readers (after all, this is a Scientific American article), so she let the reader figure out what she was saying.

I really am trying to include a picture in every post; I admit this is a stretch, though I suppose if Ms. Begley made it into The Simpsons, she has to be good, right? Can you find the goofs in Bart's writing?

Finally, I must issue a warning. In technical writing, use the more specific verb both times. Yes, it’s not as smooth, but it removes ambiguity, the bane of technical writing. In tech writing, you want to leave absolutely no question about your meaning, and you may sacrifice smoothness to do so. Take our example sentence. The words “…does science” is a construction you sometimes see, “do science, doing science, to do science.” That is definitely not the meaning in our example sentence.

Next post: I might have some more grammar humor.