Monthly Archives: April 2012

What’s the Difference? “Use” vs. “Utilize”

It’s common in technical writing to see sentences like, “Utilize the Contact Information page to see Customer Support information.” This practice has always baffled me. Why use a three-syllable word when a one-syllable word–“use”–works just as well? My only guess is that the writer thinks “utilize” sounds more formal (read: legitimate) than its garden-variety cousin. But this is just wrong thinking on so many levels. For one thing, no one that I know says “utilize” in everyday speech. For another, there’s the syllable issue. And there’s one more thing. On a mission to dissuade writers from using (utilizing) such balderdash, I researched the definitions and uncovered a subtle, yet significant, …

Continue reading

Posted in Uncategorized.

Ditch the Sales Pitch: The Final Analysis

All this week I’ve been rewriting a paragraph someone from marketing wrote for a technical manual. I had one goal: To make the paragraph useful to its audience. (Do I need to argue that something written for a business manager is useless to a developer?) To get this done, I had to: Focus on the customer while providing information about the product. Change tenuous terms to tangible ones. Excise the erroneous information. Find and state what the product delivers. Here’s the original paragraph: The ACME automated Verification of Student Registration service enables customers to obtain verification of a student’s enrollment status.  This service was developed in response to customer requests …

Continue reading

Posted in Uncategorized.

Ditch the Sales Pitch: Hidden Treasures

This week on the blog I’ve been transforming a shmoozy, solicitous paragraph in a technical manual to one that is clean, concise, and free of any whiff of the sales pitch. On Monday I highlighted all the problems with the paragraph. Tuesday I rewrote the first sentence. And yesterday I analyzed and then deleted the second sentence. Here’s the paragraph after all this work: Using the ACME automated Verification of Student Enrollment product, customers can verify a student’s enrollment status. ACME offers this service with quick turnaround searches, and with easy-to-read reporting and output.  The solution includes an image of the student’s Certificate of Enrollment form from the university in …

Continue reading

Posted in Uncategorized.

Ditch the Sales Pitch: The Riddle of Redundancy

Yesterday I revised the first sentence of our problem paragraph by making the customer the subject of the sentence, using verbs that put the customer, not the product, in control, and shortening a verb phrase into one word. Now I’d like to look at the paragraph’s redundancies. Here’s the paragraph today (with yesterday’s changes in bold). Using the ACME automated Verification of Student Enrollment product, customers can verify a student’s enrollment status. This service was developed in response to customer requests to identify students who are enrolled in college, and to apply best practices when reviewing drop-out and discontinuation activities.  ACME offers this service with quick turnaround searches, and with …

Continue reading

Posted in Uncategorized.

Ditch the Sales Pitch: Tone and Verb Vibes

Here’s what I know about the tone of our problem paragraph: It wants to sell me something. How do I know? Here are some clues: It uses vague adjectives: “quick” turnaround time; “easy-to-read” reporting and output; “best” practices It uses abstract nouns: “reporting and output”; the “solution”; best “practices” It uses verbs that put the product in control of the user: The service “enables” customers  It uses three-part verbs when one would work better: “…obtain verification of…” You get the idea.  We’ve already established that this specification is here to inform, not to sell. So let’s rewrite the first sentence to solve some of these problems. Here’s the original:   …

Continue reading

Posted in Uncategorized.

Ditch the Sales Pitch: The Mission

In “Ditch the Sales Pitch,” I posted a paragraph from a technical manual I’d been asked to rewrite. The paragraph reeked of sales lingo and other vagaries. Having transformed the monster into something more informative, I thought I’d share how I did it in case you face such a task yourself. To give us a sense of the task at hand, I’ve marked the flaws in the offending paragraph here. In the paragraph above, I’ve identified these problems: Inappropriate tone (“Buy me!”) Complicated verb forms, and what I like to call “controlling” verbs Point of view (subject vs. object) Vague promises with no details to back them up Redundancies Unnecessary …

Continue reading

Posted in Uncategorized.

Ditch the Sales Pitch

Recently a developer asked me to rewrite an API spec that someone from Product Development had written. I asked a few questions: Is this a pre-sales doc, or a post-sales doc? (If it’s pre-sales, I kick it into Marketing’s Inbox.) Is it for developers or for end users? (The answer to that question tells me how technical I must get in the document.) Given that the doc in question is an API spec, I already knew that it was a post-sales endeavor aimed at developers, but I asked anyway. Then, when I opened the document, I read this (I’ve modified the details to disguise the product itself): The ACME automated …

Continue reading

Posted in Uncategorized.

Writing How We “Talk”

Yesterday I implied that tech writers should write as people talk. Then last night, as I was reading linguist and Columbia professor John McWhorter’s book What Language Is, I realized what I proposed might be a little unrefined. In the chapter “Language Is Spoken,” McWhorter makes the point that the sounds we use (phonemes) to say the words in our language don’t represent the words themselves. For example, “Walking” is pronounced “wawekin” (with no hint of the l or the soft g in the word). (He uses lots of professional phonemic symbols in the text, but I think you get my gist.) So in fact, maybe saying we should write …

Continue reading

Posted in Uncategorized.

Because “Writer” Is in the Job Title (or Should Be)

I’m confused. I’ve spent the last hour or so perusing other technical writers’ blogs. I love doing this. So many of us are creatives at heart; blogging draws out our warmer side. Today, however, I noticed that so many blogs about technical writing really, well, aren’t. A popular blogger I like recently posted an ode to grapefruit. (I kept waiting for the analogy to technical writing, but none came.) Another one used her monthly post to announce a career coup. (Congratulations.) Many, many others discuss tools and technology, and not much else. When I started this blog, I wasn’t sure where I was going with it. I just knew I …

Continue reading

Posted in Uncategorized.