The Dirty Little Secrets of a Technical Writer

Technology journalist Michelle Bruno contributed today's post. She covers technology and face-to-face meetings in her weekly newsletter, Event Tech Brief.

One might marvel at how I, someone who literally cannot navigate the remote controls of the television set, can write about computer networks and software. It’s really very simple.

The first thing I do when confronted with a particularly complex project is avoid panic. I know now there will be a point at which everything makes sense. It’s just a matter of time.

If the client has not given me source materials, which is rare, I create my own library of research—pulling from Google Scholar or scientific journals and magazines accessed from the library of a local college (a benefit of being an adjunct faculty member).

Almost always, I print the resource materials out on paper and highlight them with a colored marker. As I scan, I begin to formulate an outline in my head.

If I become blocked or overwhelmed, I take a nap.

No writer, even the most experienced, can know everything about everything. That’s why subject matter experts are my best friends. Most software engineers or network administrators are interested that I’m interested and indulge my curiosity.

No matter what I write, every word on the page is still a part of speech: noun, adjective, verb, adverb and so on. 

For example, network, cloud, and machine are nouns. Virtualize, orchestrate, and provision are verbs. It’s critical to get everything in the correct slot.

Structure is very important to me. Even in technical writing, I try to make sure every opening paragraph gives the reader a clue about what they will learn as they read on. 

Every paragraph I write has a topic sentence. If I start out with a list in the first paragraph, I make sure the explanatory paragraphs in the body are in the same order as the items in the list. 

While attempts to be humorous or ironic are normally ill advised in technical writing, I still try to be elegant and clever. Words are still my children and I try to present them in the best light possible.

When I’m not writing, I read. I look for structure and elegance even in the most technical of articles. It’s a blessing and a curse.

I edit as I write. Most of the time I spend more time on the opening paragraph than I do on the entire article. I can’t get comfortable until my direction for the piece is set.

When I finish a project, I deliver it to the client and never read it again for fear I might find a comma out of place or begin agonizing over a word choice.

Technical writers receive exactly zero feedback. Most of the time, my efforts aren’t even acknowledged (one reason I blog). So, to get some warm fuzzy, I share the paper with my husband, who always says, “How the hell do you write stuff like this? You can’t even turn on the TV set.” I just smile.

Postscript by Bob James: Want a weekly dose of wicked good insight?

Subscribe to Event Tech Brief. It's free, and nobody covers the beat better. 

Nobody.

Do Long Engagements Lead to Marriage?

In the penultimate scene of When Harry Met Sally, Billy Crystal tells Meg Ryan, "When you want to spend the rest of your life with someone, you want the rest of your life to start as quickly as possible."

As we know from chick flicks, long engagements don't usually lead to marriage.

Only in the Bizarro World of the web does anyone promise otherwise.

Advocates of long-form content insist long pieces lead to long engagements; long engagements, to sales.

How long? 

Their tests show 1,500 words are good; 2,000, better; 2,500, best.

But Kevin Delaney, editor-in-chief of the news blog Quartz, thinks differently.

As he told RetailDive, most long-form content is padded with uninteresting, B-grade matter.

“What people read online, when you look at the data, is shorter stuff that’s focused, creative and social with a really good headline. It doesn’t mean it’s unsubstantial. It just means it’s really clear about what’s interesting and focuses on that."

Long's fine, provided it's riveting; when it isn't, you want it to stop as quickly as possible.

As critic Roger Ebert once wrote, "No good movie is too long, just as no bad movie is short enough."

7 Required Reading Containers for Every Marketer

Need that perfect gift for the marketer in your life?

Try a reading container (book).

Here are my top seven picks for the year:

Daily Rituals. Mason Currey's little book delivers an enchanting look at the work-habits of nearly 200 composers, filmmakers, novelists, philosophers, playwrights, painters and poets.

Email Marketing Rules. Moses took four decades to write his laws. So we should be grateful it's taken only half that time for someone to codify the rules of email marketing. Chad White's encyclopedic treatment is a must-read.

The Content Code. Mark Schaefer makes all the other social media gurus look like chumps. Want to crack the code? Crack open this book! And if you want more social media marketing secrets, read Jeffrey Rohrs' Audience.

Communicate to Influence. Speech coach to the stars Ben Decker shares his secret method for swaying any audience. Learn why triads are the "perfect framework" for sales pitches, product launches, motivational talks and business briefings.

Trust Me, I'm Lying. Media manipulator Ryan Holiday's book does for the Internet what The Jungle did for meat packing. Trust me, you'll never read Business Insider, The Daily Beast, Drudge Report, BuzzFeed, Politico or Huffington Post with credulity again.

Writing Tools. Roy Peter Clark's advice to writers, simply put, is the best book of its kind. And if you want to really impress the marketer in your life, pair it with a copy of William Blundell's classic, The Art and Craft of Feature Writing.

Born to Blog. Blogs are foundational to social success, and Mark Schaefer's street-smart advice is priceless.

3 Phrases You Must Not Use in 2016

The year's about to end.

It's list time.

Mine consists of three pretentious phrases everyone in business should retire.

Across the enterprise. Romulans fired torpedoes across the Enterprise. Throughout the company is clear enough.

Take offline. Employed by teleconference leaders to quash unwelcome discussions. If drop it is too brusque, hold that thought would work.

Go viral. Shared content shouldn't be likened to SARS and Ebola. Become popular sounds just fine.

Which phrases would you ban?

Unnatural Acts

Why do we encounter so many inexpert emails, articles, ads, books and blog posts?

The fault is not in our stars, but in ourselves, says psycholinguist Steven Pinker in The Sense of Style.

As Darwin observed, for human beings the act of writing, unlike speaking, is unnatural.

While we master the art of conversation as kids, we wrestle for years—decades—to learn to communicate artfully in writing.

Unlike speaking, writing isn't genetically wired. Good prose, in fact, demands that writers commit "unnatural acts," Pinker says.

Those acts begin in a fairy tale.

To communicate well, the writer must make believe she's conversing with someone.

"The key to good style, far more than obeying any list of commandments, is to have a clear conception of the make-believe world in which you're pretending to communicate," Pinker says.

What should your make-believe world look like?

Pinker describes it eight minutes into his delightful 50-minute talk before the Royal Institution, Linguistics, Style and Writing in the 21st Century. 

Check it out.

Why is So Much Business Writing So Bad?

Why is so much business writing so bad, irritating customers and wasting workers' time?

It begins with box checking.

In the race to "get it done"—and check yet another box—marketers and product managers flout good-writing fundamentals.

Foremost, as journalist Shane Snow points up, is simple diction.

Readers are impatient drivers. Simple diction lets them speed. They want writers to keep the highways open. And they prefer the ones who do.

To prove the point, Snow entered passages from a variety of popular writers—including Cormac McCarthy, Stephen King, J.K. Rowling, Seth Godin and Malcolm Gladwell—into five proven calculators of "reading ease."

The resulting scores showed:

• McCarthy, King and Rowling write for people with fifth-grade reading skills; and

• Godin and Gladwell, for people with eighth-grade skills.

Snow asks: Do readers love only these writers' story-telling abilities? Or do they also love their approachability—in other words, their simple diction?

With half the US population reading at no better than an eighth-grade level, the answer's obvious. 

Yet most business communications are written as if we all could read like grad students, who don't slow down for Latinate words, jargon, run-on sentences, and page-long paragraphs.

But unapproachable diction isn't the only problem.

Good writing takes time. Time and the determination to inform, research facts, and think critically.

It takes more than the urge to check another box.

Ing-lish Spoken Here

Junior copywriters love to add "ing" to verbs.

Poor souls. 

No one's told them it weakens the most powerful words in our language.

In Writing Tools, Roy Peter Clark gives two reasons why "ing" sucks strength from writing:

• It adds a syllable. Simple's better. Adding syllables complicates verbs.

• It often appears in a crowd. Writers who love "ing" tack it onto every verb they use. The words quickly begin to resemble each other.

In a 2002 article in The New York Times, linguist Geoffrey Nunberg first named the latter habit "ing-lish."

The junior copywriter's defense: "Marketing copy breaks the rules. Ing-lish is fine. No, it's even better. It's perfect."

Lovers of ing-lish think "ing" strengthens every verb by adding a sense of the here and now; of progress; of the urgent.

But, before you decide whether ing-lish is perfect, consider a few alternate taglines:

• Avis. We're trying harder.

• Nike. Just doing it.

• California Milk Processors. Getting milk?

• M&M: Melting in your mouth, not in your hands.

• State of New York. I'm loving New York.

• Burger King. Having it your way.

• Hamlet. Being, or not being, that is the question.

NOTE: Thanks go to graphic designer Clif Dickens for his "honest" tagline above. Enjoy more honest taglines here.

Prevent Slow Burn

In the 1930s, film-goers loved comedian Edgar Kennedy for his mastery of the "slow burn."

When thwarted by a foe, Kennedy would glower, then slowly rub his hand over his face as he fought off—and inexorably succumbed to—his fury.

I find myself doing the slow burn whenever I encounter a self-indulgent blogger; the writer who, rather than informing me from the get-go, drowns me in silly eyewash.

A prime example can be found in a recent post on Hubspot, "Why Blog? The Benefits of Blogging for Business and Marketing."

The author uses 118 words to tell us why she's telling us what she plans to tell us. Her long warm-up leaves me cold:

I had a co-worker email me the other day asking for a blog post about the benefits of business blogging. "It's for a friend," she said.

Sure it was.

I told her I'd shoot over one of our up-to-date blog posts about why businesses should blog and... I couldn't find one. Whoops. Quite the meta mistake.

So I'm doing it now. If you're trying to explain one of the core tenets of inbound—business blogging—to your boss, a coworker, your mom at Thanksgiving, whomever, then send them this post. I hope it helps. For even more reasons why you should blog for business and marketing—and how to get started—download our free e-book here.

Please, spare readers false starts—especially jejune ones.

Remember, only you can prevent slow burn.

6 Energy-Saving Tips for Communicators

Self-taught his trade, Jack London said he discovered how to "transmute thought, beauty, sensation and emotion into black symbols on white paper" from Herbert Spencer's now-neglected 1852 essay The Philosophy of Style.

From Spencer, London "learned that the right symbols were the ones that would require the expenditure of the minimum of my reader’s brain energy, leaving the maximum of his brain energy to realize and enjoy the content of my mind, as conveyed to his mind.”

Foreseeing today's attention-deficient audiences, Spencer preached "the importance of economizing the reader's or hearer's attention, to so present ideas that they may be apprehended with the least possible mental effort."

"A reader or listener has at each moment but a limited amount of mental power available," Spencer says. Most of that energy is consumed when the brain takes in the written or spoken symbols, leaving little to spare for comprehension.

Spencer insists, "the more time and attention it takes to receive and understand each sentence, the less time and attention can be given to the contained idea; and the less vividly will that idea be conceived."

To compensate for audiences' sparse mental energy, writers and speakers should economize; or, as Spencer suggests, follow "the law of easy apprehension."

I've boiled his law down to six tips:

1. Avoid long, Latinate words. Use instead the short Anglo-Saxon ones we learned as kids. Use Latinate words only to express big ideas, because "a voluminous, mouth-filling epithet is, by its very size, suggestive of largeness or strength," and "allows the hearer's consciousness a longer time to dwell upon the quality predicated."

2. Use words that sound like their meanings. "Both those directly imitative, as splash, bang, whiz, roar; and those analogically imitative, as rough, smooth, keen, blunt, thin, hard, crag; have a greater or less likeness to the things symbolized; and by making on the senses impressions allied to the ideas to be called up, they save part of the effort needed to call up such ideas, and leave more attention for the ideas themselves."

3. Use specific, instead of generic, words. "If, by employing a specific term, an appropriate image can be at once suggested, an economy is achieved, and a more vivid impression produced.

4. Watch your word sequence. The order of your words should allow readers' or listeners' brains to process each as it arrives, with minimum effort. Put subjects in front of predicates, and give priority to big ideas by placing them at the front of the sentence. "The right formation of a picture will be facilitated by presenting its elements in the order in which they are wanted; even though the mind should do nothing until it has received them all."

5. Place subordinate parts of a sentence ahead of the main part. "Containing, as the subordinate proposition does, some qualifying or explanatory idea, its priority prevents misconception of the principal one; and therefore saves the mental effort needed to correct such misconception."

6. Place related words and expressions near one another. "The longer the time that elapses between the mention of any qualifying member and the member qualified, the longer must the mind be exerted in carrying forward the qualifying member ready for use. And the more numerous the qualifications to be simultaneously remembered and rightly applied, the greater will be the mental power expended, and the smaller the effect produced."

Don't have the energy to read Herbert Spencer's The Philosophy of Style?

Good news: there's a free audiobook.

Lean In

Businesses sink billions into "designing out waste" and "building lean in," but spend nothing to discourage verbosity.

They'd do their bottom lines a big favor by sending every employee the link to John McPhee's latest article in The New Yorker, "Omission."

McPhee clarifies why lean writing is good writing: it's what's left out that counts.

Lean writing comes from heavy editing, which McPhee compares to shortening a train. 

"The idea is to remove words in such a manner that no one would notice that anything has been removed," he says. "It’s as if you were removing freight cars here and there in order to shorten a train—or pruning bits and pieces of a plant for reasons of aesthetics."

Not only editors, but artists, designers and comedians understand that, always, less is more.

Hemingway called it the Iceberg Theory:

"If a writer of prose knows enough about what he is writing about, he may omit things that he knows and the reader, if the writer is writing truly enough, will have a feeling of those things as strongly as though the writer had stated them. The dignity of movement of an iceberg is due to only one-eighth of it being above water.”

Watch Those Weasel Words

Weasel words—defaults for bureaucrats and politicians—are qualifiers that nervous speakers and writers bank on for cover.

Avoid them, because the more you water down thoughts with weasel words, the less clear and certain your speech and writing become.

For example, instead of saying, IT possibly seems to have suggested that Aptly may no longer be supported after December 31, say IT may no longer support Aptly after December 31.

At the same time, avoid absolutes like always, never, will not, cannot and nothing is worse than.

Avoid statements like, Nothing is worse than displaying your password. Really? What about your company's recent job-cuts, the drought in California, or Syria's civil war?

The King of Clockwork

I envy the grimacing joggers I pass on my way to work every weekday morning for their samurai discipline and inveterate svelteness (a quality I lack).

Leadership and personal productivity experts goad us to rise above mediocrity by forming useful habits.

Surpassing champs like Kant, Edison and Einstein, the king of the clockwork habit could well be Victorian novelist Anthony Trollope.

He wrote with such regularity, that he produced 47 novels—plus 32 plays, short stories and nonfiction books—in his spare time.

Stephen King (with 60 novels and 200 short stories, no slouch either) describes Trollope's habit in his memoir, On Writing: 

"His day job was as a clerk in the British Postal Department (the red public mailboxes all over Britain were Anthony Trollope's invention); he wrote for two an a half hours each morning before leaving for work. This schedule was ironclad. If he was in mid-sentence when the two and a half hours expired, he left that sentence unfinished until the next morning. And if he happened to finish one of his six-hundred-pound heavyweights with fifteen minutes of the session remaining, he wrote The End, set the manuscript aside, and began work on the next book."

3 Words You Should Never Ever Use

We reward disruptors like Uber and Airbnb for obliterating needless stuff.

You can reward audiences by eliminating these three needless words from your writing.

That

Writers too often use “that” without purpose. Whenever you use the word, ask yourself whether you can ditch it; chances are, you can. I think that you will find that our prices are competitive becomes I think you will find our prices are competitive.

Very

Writers hope to intensify words by slapping "very" in front of them; but the word adds no value. Our CSRs are always professional reads better than Our CSRs are always very professional.

Awesome

Overuse has sullied “awesome.” The word once meant "inspiring" or "daunting," and was reserved for descriptions of mountains and miracles, not candies and cupcakes. So avoid it. Our cloud suite is awesome is less credible—and more cheesy—than Our cloud suite is first rate. (Least cheesy might be Our cloud suite is comprehensive, reliable and easy to use.)

But never say never: needless words can enhance your writing.

E. B. White, a crusader for concision, once advised a fellow writer:

"It comes down to the meaning of ‘needless.’ Often a word can be removed without destroying the structure of a sentence, but that does not necessarily mean that the word is needless or that the sentence has gained by its removal. If you were to put a narrow construction on the word ‘needless,’ you would have to remove tens of thousands of words from Shakespeare, who seldom said anything in six words that could be said in twenty. Writing is not an exercise in excision, it’s a journey into sound. How about ‘tomorrow and tomorrow and tomorrow?’ One tomorrow would suffice, but it’s the other two that have made the thing immortal."

Now that is very awesome!

Good Storytelling isn't Measured in Words

When it's concise, even long-form writing seems short.

Magazine writing proves the point.

Nonfiction writer Joan Didion mastered concision by writing for magazines like Vogue, Mademoiselle, and Life for decades, says Louis Menand in The New Yorker.

Didion, the "quintessential magazine writer," drew readers into her stories by leaving things out (the fiction writer's trick).

She developed "methods of economizing the exposition and managing the reader’s experience, ways of getting the reader to participate in the job of making sense of whatever it is that the writer is trying to think through," Menand says.

Didion mastered concision because she was forced to. When a writer works for a magazine, Menand says, her ability to write concisely gives her a Darwinian edge.

"The job of the magazine writer is never to give readers a reason to stop before they reach the end. The No. 1 sin in print journalism is repetition. Pages are money; editorial space is finite. Writers who waste it don’t last. Conditions demand a willingness to compress and a talent for concision."

A $49 Cure for Tone Deafness

Tone deaf? 

Well, good news: there's an app for that.

For only $49 a month, Crystal will provide you the empathy you sorely lack.

A Gmail add-on, Crystal scrapes your colleagues' social media posts; analyzes the posts; and attaches to each individual one of 64 different personality types.

Then, whenever you craft an email, the app prompts you to revise your words and ideas, so they sync with the reader's personality type.

Autocorrect, meet Myers-Briggs.

Crystal also suggests when to tighten your message; toss in an emoji; or use a little humor to soften things.

The end result? All your emails turn out more pleasant and pithy.

Crystal's developers claim their algorithm assigns personality types with 80% accuracy.

You can boost that accuracy, too, by answering multiple-choice questions about a colleague (such as, "If there were a conflict at work, how would he or she react?").

Please Kill the Zombies

Clichés are writing's walking dead.

You can pretend they're harmless, but soon they'll take over—and come back to bite you.

A scrupulous writer kills clichés when they begin to pop up in her work.

"A scrupulous writer, in every sentence that he writes, will ask himself at least four questions," says George Orwell in his 1946 essay Politics and the English Language:

• What am I trying to say?
• What words will express it?
• What image will make it clear?
• Is the image fresh?

A scrupulous writer will ask, in addition:

• Could I say it in fewer words?
• Have I said anything avoidably ugly?

"But you are not obliged to go to all this trouble," Orwell says. 

"You can shirk it by simply throwing your mind open and letting the ready-made phrases come crowding in. They will construct your sentences for you—even think your thoughts for you, to certain extent—and at need they will perform the important service of partially concealing your meaning even from yourself."

Before you click publish, do readers—and yourself—a favor.

Please kill the zombies.

Save $26,041 per Employee with this Simple App

A 2008 study by SIS International Research showed that an employee squanders 17.5 hours a week deciphering faulty communications in the workplace. The researchers estimated the wasted hours to cost a small company $26,041 annually.

No surprise. 

Communication, like every business activity, is prey to Murphy's law. 

Any message that can go wrong will.

But there's a simple app available that will staunch the flow of red ink.

It's called clarity, and it's friendly and easy to use:

• Turn long sentences into two or three shorter ones.

• Chop big blocks of text into separate paragraphs.

• Use connectors—words like although, but and because—to join ideas together.

• Avoid pronouns—words like it, we, they and this. Use pronouns sparingly and you won't write a sentence like: Advise customers they are guaranteed to work 24/7 when we upgrade our servers.

• Be careful with directions—words like about, before, on and over—and you won't write a sentence like: Before lunch with the client we should hash out next year's price increases.

You can get the full download on clarity from "grammarphobes" Patricia O'Conner and Stewart Kellerman's You Send Me: Getting It Right When You Write Online.

Alpha Dogs

I'm as much a fan of Larry Page, CEO of newly formed Alphabet, as the next guy.

Without his efforts, I'd still have to haul around dictionaries and encyclopedias; and I'd be writing blog posts with software other than Blogger.

But Larry overstates and overwrites, as shown in his August 10 letter to investors.

While exemplary in tone, the letter is littered with dogs.

Borrowing from some new-age infomercial, he tells investors (twice) that he's "super excited" about Google's prospects, and "really excited" to announce Alphabet.

Who wouldn't be? The reorganization lets him put "tremendous focus on the extraordinary opportunities" at Google, and lets him continue to work alongside its new CEO, a diversion Larry is "tremendously enjoying."

And why not? Google's new CEO brings about "amazing progress" and "incredible growth."

It all adds up to a "very exciting new chapter" in Google's life.

And it all spells "hooey."

Overwriting betrays under-thinking.

Overstating strains credulity.

3 Easy Hacks to Make You a Great Writer

Imagine earning $1 for each encounter you have with some grifter hawking simple hacks for turning your mediocre copy into gold.

You'd soon be another Warren Buffet.

But life's just not that easy… until now.

You've reached Mecca on your journey to $1 million every month.

That's because I'm pulling back the curtain to reveal the three most awesome writing hacks ever offered:

1. Read. 

2. Read. 

3. Read.

These three magic bullets come endorsed by a NOBEL PRIZE WINNER.

On April 16, 1947, novelist William Faulkner led a Q & A session in the English department's creative writing course at Ole Miss.

During the session, a student asked him, "What is the best training for writing?"

Faulkner advised, “Read, read, read! Read everything—trash, classics, good and bad; see how they do it. When a carpenter learns his trade, he does so by observing. Read! You’ll absorb it. Write. If it is good, you’ll find out. If it’s not, throw it out the window.”

So that's it. Read, read, read. 

Killer!

Wait, there's more in my pipeline!

In my next post, I'll share the greatest hack in the history of modern media.

For now, here's a teaser.

A Pen as Mighty as His Sword

In his masterful Mask of Command, the late military historian John Keegan makes the case that Ulysses Grant's dispatches were as much responsible for victory as his grasp of tactics and infamous determination.

General George Gordon Meade’s chief of staff Theodore Lyman once wrote, “There is one striking thing about Grant’s orders: no matter how hurriedly he may write them on the field, no one ever had the slightest doubt as to their meaning, or ever had to read them over a second time to understand them."

It was clarity, simplicity and directness that made Grant's dispatches so astonishingly effective.

Lyman said Grant's dispatches "inclined to be epigrammatic without his being aware of it,” chiefly because the general used “plain and unmistakably clear words.”

Three examples:

In February 1862, hunkered before Fort Donelson, Grant sent this note to Confederate General General S.B.Buckner:

Sir, Yours of this date, proposing armistice and appointment of commissioners to settle terms of capitulation, is just received. No terms except an unconditional and immediate surrender can be accepted. I propose to move immediately upon your works.

In April 1864, while advancing on the Wilderness, Grant dispatched the following order to Meade:

Lee’s army will be your objective point. Wherever Lee goes, there you will go also.

And after Spotsylvania, in May 1864, Grant sent the army's chief of staff, Henry Halleck, this note:

We have now ended the 6th day of very hard fighting. I propose to fight it out on this line if it takes all summer.

When your goal is clarity—to write so that your readers will understand exactly what you mean—write like Grant, with simplicity and directness. 

Clarity eliminates ambiguity and confusion, and makes reading effortless.