They’ll thank you when…

It’s Thanksgiving week here in the U.S. As a blogger it’s tough not to succumb to the temptation to write the dreaded (and trite) 2,387 things I’m thankful for.

readingLet’s turn that listicle on its head.

As a technical writer, what can you do that will make your readers thankful?

Here’s my list.

Tell them a story. Mark Baker asserts that we should see ourselves as story providers rather than content providers. He’s right. Stories resonate with people in a way that simple content, or information, simply can’t. In technical writing, the story’s hero is your reader, who’s trying to accomplish something or learn something.

Give them more than just a narrative. A narrative might be mildly interesting, but a story is more than that. A story is a narrative with facts, or data, baked into it. In technical writing, the data supports the story of your reader meeting their objective.

Provide everything they need, and not one iota more. Don’t leave out any essential data. Don’t make the task appear simpler than it really is. But don’t pack your story with extraneous stuff that captures the fancy of your subject-matter expert.

Write in the proper tone. This will vary depending on who you’re writing for. Crisp and professional for the IT specialist who’s setting up a network; more casual for the weekend warrior who’s assembling a backyard barbeque grill. A tone that works for American readers might not work for Asian readers. It’s all about the fundamental rule of technical writing: know your audience.

Do those things, and your readers will be grateful, even if they never say “thank you” to your face. And you’ll have the satisfaction of knowing that you’ve provided something of value.

What would add to this list?

As democracy is perfected…

H.L. Mencken wrote this in the Baltimore Sun in 1920. It’s as if he’d been reading today’s political headlines.

Portrait of H.L. Mencken

H.L. Mencken, the Sage of Baltimore (source: Wikipedia)

When a candidate for public office faces the voters he does not face men of sense; he faces a mob of men whose chief distinguishing mark is the fact that they are quite incapable of weighing ideas, or even of comprehending any save the most elemental — men whose whole thinking is done in terms of emotion, and whose dominant emotion is dread of what they cannot understand. So confronted, the candidate must either bark with the pack or be lost…

All the odds are on the man who is, intrinsically, the most devious and mediocre — the man who can most adeptly disperse the notion that his mind is a virtual vacuum. The Presidency tends, year by year, to go to such men. As democracy is perfected, the office represents, more and more closely, the inner soul of the people. We move toward a lofty ideal. On some great and glorious day the plain folks of the land will reach their heart’s desire at last, and the White House will be adorned by a downright moron.

Yes, Mencken was a cynic. But in this case he was frighteningly close to the truth.

As a counterpoint, of course, we have Churchill’s democracy is the worst form of government except all those other forms that have been tried.

Something to ponder on your Friday.

Making mistakes and learning from them

The recently concluded World Series will be remembered for lots of things, including a surprising number of mistakes by the participants. We can learn from the mistakes we saw during those games — and we can take heart from them too.

In the eighth inning of Game 1, with the score tied 3-3, Royals first baseman Eric Hosmer mishandled a ground ball and allowed the Mets to take the lead. Much later, in the 14th inning, Hosmer drove in the winning run.

Eric Hosmer misplaying a ground ball

Eric Hosmer boots a ground ball…. {Source:

Lesson 1: Your mistake probably isn’t the end of the world. Hosmer didn’t brood over his mistake. He kept his head up and seized an opportunity to make amends. (He seized another opportunity in Game 5 when, in perhaps the most memorable play of the Series, he scored a crucial run with his daring baserunning.)

In Game 3, with two men on base, Royals pitcher Franklin Morales fielded a ground ball and thought about throwing it home. Then he thought about throwing it to first base. By the time he finally threw the ball — to second base — it was too late. The batter and both runners were safe.

Lesson 2: Plan ahead. Good baseball players know what they’ll do before the ball comes to them. We, too, shouldn’t wait until a situation arises before we know what we’ll do.

Eric Hosmer at bat

….and then drives in the winning run (Source: New York Times)

In Game 5 Mets manager Terry Collins decided to replace his tiring pitcher, Matt Harvey, after eight innings. TV viewers watched Harvey in the dugout, imploring Collins to change his mind. Collins relented. Harvey stayed in the game, gave up a walk and a double, and the Mets went on to lose.

Collins made a mistake by trusting his heart over his better judgment. He took full blame, saying “you gotta support your players once in a while” and “we’ll get better because of it.” Collins might very well be right. the Mets lost this game (and the Series). But perhaps their players gained a greater respect for their manager, which will pay off in the long run.

Lessons 3 and 4: When you make a mistake, own it. And don’t be afraid to trust your heart: the long-term intangible benefits might outweigh the short-term costs. While these lessons are true for everyone, they go double for leaders.

You and I try not to make mistakes. But they happen anyway. Why not resolve that next time you make a mistake, you’ll learn something from it.

What have you learned from the mistakes you’ve made?

Your Halloween treat: five tricky word pairs

This English language of ours is devilishly tricky.

Jack o'lanternFor your Halloween reading pleasure, here are five especially ghoulish word pairs.

If you use these words properly, you’ll win the respect and admiration of careful writers everywhere. If you don’t, your readers — some of them, anyway — will shriek in terror.

A new tact: Tack is what a yachtsman does to align a boat with the wind. Changing tack, or taking a new tack, sets the boat moving in a new direction. Taking a new tact simply doesn’t make sense. I can’t say it any more tactfully than that.

Don’t jive with me: Jibe, another word that comes to us from the sea, means to bring things into agreement. If your position jibes with mine, then we’re cool. But if it jives with mine, then you’re just being phony.

A rift on an old theme: I recently read a blog post in which another blogger was said to be rifting on a particular topic. A riff is a rhythmic phrase in music. A rift is a crack in the ground. Maybe the rifting blogger was making, um, wise cracks.

Now hear this: When you like what somebody has said, and you want others in the audience to listen, the expression is hear, hear! If you write here, here, that won’t get you anywhere, anywhere.

Honing in: When your focus narrows, do you home in or hone in? Do you come closer to home, or do you hone (sharpen) your sights? For my money, it’s home in — although much to my surprise, one of my favorite dictionaries, Wordnik, disagrees. So if you like to write hone in, I promise to keep my shrieking to a minimum.

At this witching season, which other homonyms (or near homonyms) have you heard being used in ways that are ghoulish?

Adapted from an article in the SDI blog, 28 October 2010

This kid’s good: spotting and nurturing talent

In August 2009, on a visit to my native New Jersey Shore, I watched the Lakewood Blue Claws win a minor-league baseball game. The Blue Claws play in Class A, which is three levels below the major leagues. The vast majority of players at that level will never make it to the majors.

But one player, the Blue Claws’ catcher, caught my eye. In the top of the sixth inning he positioned himself perfectly, received a throw, and tagged out a runner who slid directly into him. It was a smart play, and the catcher showed quick thinking and grit.

A few minutes later, in the bottom of the sixth, he lined a two-base hit and scored what turned out to be the winning run.

This kid’s good, I thought to myself. Continue reading

Who do you pick for the project?

You joined the team a few months ago as its manager. Now a challenging new project is on the horizon, and you have to decide which team member gets the assignment. Who do you pick?

People in an officeRoy has been part of the team for years. The previous manager told you that he struggled in the past. But since you’ve been here, it’s as if a light went on: Roy’s work has been top-notch. Is Roy past his struggles and up to a challenging new assignment?

Bill goes through his workday with a swagger. He’ll tell you that he can handle anything you throw at him. And so far he has, although you haven’t asked him to do anything that was particularly hard. Is Bill just a braggart, or do you trust him to walk the talk?

Melanie’s work has always been good but not outstanding. A few months ago, when Melanie’s project encountered some unexpected bumps — not of her making — she surmounted the problems and delivered a great outcome. Was it a fluke, or is Melanie ready to rise to the occasion again?

Connie is the youngest member of the team, eager to learn and willing to do things in new ways. She’s already suggested some innovations that have paid off. Can Connie’s energy and new ideas overcome her lack of experience?

My take: don’t rely too much on the past, especially on things you’ve heard but haven’t observed firsthand. Instead, align your people’s current abilities with current and future needs.

Logo for Major League Baseball postseasonThe people in this story are fictitious, but I didn’t just make them up. They represent the personalities of the four teams that remain in this year’s major-league baseball playoffs: the Royals, Blue Jays, Mets, and Cubs, respectively.

When you watch baseball, or any sport, you learn that players and teams change and grow. As a manager you should acknowledge that growth: judge your people on who they are today rather than basing your expectations on who they used to be.

So….Who gets assigned to the new project? Why would you pick that person?

Who would I assign to the project? Ask me after the World Series.

Defining what you and I do

I remember trying to do this in STC without getting too far. Now tekom, the European professional society, has taken a stab at defining the job duties of technical communicators.

Graph showing 7 major areas of competency

Source: tekom

I think they’ve done a pretty good job.

Start with the 7 areas of competence (pictured). These aptly describe, in broad terms, the tasks associated with each stage of the content lifecycle.

Then look at the 27 fields of competence. For example, Content Creation — one of the 7 areas of competence — breaks down into identifying information sources, acquiring and selecting information, using tools to create content, and so forth. You can see these 27 fields in the Profiling Tool, a self-assessment that anyone can take.

Why a competency model?

All of this is a lot to digest. But by and large it reflects our jobs pretty well. In cases where I might quibble with the tekom definitions, it could be because I’m steeped in my own industry and tekom has tried to make the lists industry-agnostic.

Tekom identified four major stakeholder groups for the competency model:

  • Company managers and personnel departments, who draw up lists of job requirements
  • Educational institutions that develop training programs and curricula
  • People who want further education in Tech Comm
  • Practitioners who want to enter the field or enhance their skills

But that’s not all. Continue reading

The impulse to do it now

I’m doing a content inventory and I notice that some white papers have the client’s old logo on them. My first impulse is to fix them — “I’ll just apply the new template. Won’t take 5 minutes.” — even though I know full well that a content inventory has nothing to do with evaluating or fixing the content.

Person editing

This is a stock photo. But I really did look like this about 20 years ago. OK, 30.

I’m handed a 50-page book to edit. Midway through page 1, my right hand begins twitching as I resist the impulse to grab a red pen and start making corrections — even though I know full well that a good editor reads the document through, learning about the author’s style and the conventions followed, before making corrections.

It probably has a name, this impulse to tackle a big job by whacking away at little bits of it. But I don’t know what it is. I must not be the only person who’s afflicted by it. But only recently have I begun thinking about why I’m afflicted. Continue reading

Truth or ignorance? Confidence or fear? It’s time to choose

This week, 14-year Ahmed Mohammed was led away from school in handcuffs after police and school officials thought his homemade clock looked like a bomb. You probably heard about it, as I did, on Facebok or Twitter.

I find so many aspects of this story appalling.

Photo of Ahmed Mohammed

14-year old Ahmed Mohammed (Source: Dallas Morning News)

A bright kid with a passion for engineering — the kind of kid we should be celebrating — was humiliated and outrageously accused. Americans are increasingly skeptical of science. It seems now that we’re feeling threatened by science as well.

Worse, none of the supposed grownups in the story bothered to learn the truth. Confronted with the truth — Ahmed insisted all along that the device was a clock — they chose to persist in their ignorance.

Worst of all, Ahmed was singled out because he has brown skin and a Muslim name. Don’t tell me he wasn’t. He never would’ve been handcuffed if he’d looked like Wally Cleaver and his name had been Josh or Ryan.

Say what you want about this episode. It showed people — educators and police officers, the very people who should know better — behaving at their absolute worst.

Here’s the thought that echoed the loudest to me: Continue reading

John McPhee on writing for your reader

John McPhee writes in this week’s New Yorker about two essential skills for every nonfiction writer: knowing what to take out, and letting readers experience the story for themselves. For McPhee, the two are inextricably linked.

Because McPhee expresses his ideas far better than I could, I’ll use his words and then provide commentary.

Ideally, a piece of writing should grow to whatever length is sustained by its selected material — that much and no more.

Photo of John McPhee

John McPhee (Source: Office of Communications, Princeton University)

Some of McPhee’s books and articles have grown much larger than he envisioned them initially, because as he dug deeper he found more and more that was interesting. Still, he says, before a story goes into final production there’s always something that would best be taken out.

He describes the bygone process of greening, in which a writer has to strike (using a green pencil) a certain number of lines from a finished magazine article so that it fits the space. He still teaches greening to his writing students. Sounds like a good idea for us technical writers as well.

Writing is selection. Just to start a piece of writing you have to choose one word and only one from more than a million in the language. Now keep going. What is your next word? Your next sentence, paragraph, section, chapter? Your next ball of fact. You select what goes in and you decide what stays out. At base you have only one criterion: If something interests you, it goes in — if not, it stays out.

I like the idea that writing is a progression — from the starting point to the next thing, then to the next. Even though you’re writing nonfiction you’re still writing a story, and as the writer you get to decide how the story will go.

Since my background is in technical writing, I find myself wanting to argue that the “one criterion” shouldn’t be what interests me but should be what interests my reader. Yet I think I understand what McPhee is saying: As the one who’s doing the informing, I’m responsible for choosing what my reader will need or want. My reader can’t know, and I’m shirking my duty if I force them to choose the story.

I think this is true even in an “every page is page one” environment where my reader chooses what content to read, and in what order. Within each chunk of content — each topic — I still have to provide the narrative that will lead my reader to what they need.

To cause a reader to see in her mind’s eye an entire autumnal landscape…a writer needs to deliver only a few words and images — such as corn shocks, pheasants, and an early frost. The creative writer leaves white space between chapters or segments of chapters. The creative reader silently articulates the unwritten thought that is present in the white space. Let the reader have the experience. Leave judgment in the eye of the beholder. When you are deciding what to leave out, begin with the author. If you see yourself prancing around between subject and reader, get lost.

Get lost. In the end it’s about the reader. The writer should become invisible. I’m in complete accord with this: In fact I consider it to be the prime directive of technical writing.

What do you think? Leave a comment. Tell me if you enjoyed McPhee’s piece, and what you think of his ideas on brevity and on connecting with the reader.