With context, I can see a lot

I’m passing time in Terminal C at Newark Airport, and way across the concourse a baseball game is on TV. From this distance the screen is tiny — in fact I can see only about two-thirds of it — and I can’t hear anything.

Distant TV screen at the airport

There, in the middle arch, is my baseball game.

Yet I can enjoy the game, simply because it’s baseball — a game I’ve watched since I was a kid. Even though I don’t know the players or the score, I have plenty of context for this game I’m eavesdropping on.

Similarly, one of the best things we can do as technical writers is to supply our readers with information that fits the context in which they’re reading.

Peering at the tiny TV screen, I recognize the words on a player’s uniform: East Carolina. I heard on last night’s local news that East Carolina would play Houston today for the championship of a conference whose name I don’t remember. Sure enough, the other team’s uniforms are red. Must be Houston.

I don’t know any of the players on ECU or Houston. From my vantage point I can’t tell the inning or the score. I don’t even remember the name of their conference. Still, I can see a lot:

East Carolina’s pitcher is a lanky lefthander with a nice, smooth motion. I watch him freeze a batter with a good breaking pitch — not because I can see the ball, but because I see the batter’s reaction. Now the batter is headed back to the dugout walking the same dejected walk of every batter who strikes out, from Little League to the World Series.

Years of watching baseball have supplied me with context. It’s the same with the people who read our technical content. When the content fits their context, they can make sense even out of information that’s new and unfamiliar. But information that doesn’t fit their context isn’t even information. It’s just data, with no meaning at all.

How can we help our readers fit information into context?

Use familiar terms. If the reader knows something by a certain name, use that name. This is no time to break out your thesaurus. If the reader is accustomed to the metric system, for heaven’s sake use metric measurements.

Use diagrams and illustrations that are consistent with each other in appearance and content. If possible, use diagrams and illustrations that look like ones the reader is already familiar with.

Compare new concepts to things the reader knows. John McPhee, about whom I wrote recently, is a master of this.

As I finish writing this article, dear reader, I realize that it needs to fit into your context. You might not care about baseball, or about my ruminations on the game. So I go back and rewrite the introduction, so that right away you’ll see what the article is really about. How’d I do?

What else can we do to fit content to the context in which our readers consume it?

One of the best at his (and our) craft

Photo of John McPhee

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

The genre is called creative nonfiction, and nobody does it better than John McPhee. This year marks the 50th anniversary of McPhee’s first published work, a portrait of basketball star Bill Bradley. Since then he’s written about dozens of topics — especially nature and conservation.

The Wikipedia entry for creative nonfiction distinguishes it from technical writing because the latter is “not primarily written in service to its craft.” I’m not sure what that means — it sounds like creative nonfiction is writing for writing’s sake. If you suggest to John McPhee that he writes “in service to his craft” I think he’ll be surprised.

I maintain that creative nonfiction is true technical writing. Although it might not guide a reader through a series of steps, it informs the reader about a scientific or technical subject.

Judge for yourself as McPhee describes Georgia’s Cumberland Island. Continue reading

I could’ve observed a lot by watching him

He’s smart and gifted. Yet he’s best known for his oddball aphorisms.

He was one of the best baseball players in history. Yet people who know nothing about baseball, think they know all about him.

His is one of the most remarkable personal brands I know of.

Photo of Yogi Berra

Yogi Berra from a 1956 Baseball Digest cover

Today is Yogi Berra’s 90th birthday. I’m using a photo of him from about age 30 because, as he once said: “I looked like this when I was young, and I still do.”

I like Yogi for a lot of reasons.

First, we share a given name. Lawrence Berra got the “Yogi” nickname early in life when a baseball teammate, watching him sit cross-legged waiting for his turn to play, thought he resembled a Hindu yogi. I bet you thought he was named after the Yogi Bear cartoon character. It’s actually the other way around — a testament to how popular Yogi was during his playing career.

Second, I see something of myself in him. In school I was known as a brainy kid. To fit in with the more popular kids I “dumbed it down,” intentionally using poor diction or choosing the wrong word. After awhile I discovered that not only wasn’t I popular, I was proving myself untrustworthy by trying to be something I wasn’t.

To quote one of his aphorisms, I could’ve observed a lot by watching Yogi Berra. Continue reading

Watch those connotations

connotation (n.): the associated or secondary meaning of a word or expression
in addition to its explicit or primary meaning (from the Random House Dictionary)

Marli Mesibov has a nice piece, The Meaning Behind Connotations, explaining why content strategists must consider the reader’s interpretation of the content – not just its explicit meaning.

She describes an instance where an Internet marketer used an image that offended a lot of people and then tried to blame the people for taking offense. Then she says:

If the user has a certain connotation with a term (or image), then we as content strategists can’t decide they are right or wrong. It’s our job to accept that connotation, or lose the user’s trust.

Jared Spool tweet: Semantics is about meaning; meaning is important

Words of wisdom from Jared Spool (quoted by Marli Mesibov in her article)

As any good writer knows, you have to own what you write. You’re responsible for whatever meaning is there — whether you stated it explicitly, whether you laid it between the lines, and even whether you put it there by mistake.

You don’t get to decide what meaning the reader will take away. And because it’s a question of trust, it goes to the heart of the relationship between your business and your customers.

This applies every bit as much to technical writing as it does to content strategy, since the technical content you create falls (or should fall) under the rubric of your organization’s content strategy.

So how do you keep connotations from becoming problems? Continue reading

Knowing what to do: My prayer for Baltimore

In August 1967 my family took a car trip from our home at the Jersey Shore to the Midwest, where my mother was born. Along the way we visited several cities — including Detroit, where I remember seeing the zoo and the Ford museum in Dearborn.

Somewhere along the way we stopped at White Castle for an early supper. All of a sudden a man began yelling at the top of his voice. I think it had something to do with the cashier short-changing him. Nothing special, right? Except it had been just a few weeks since the Detroit riot that killed 43 people and left 2,000 buildings destroyed.

What I remember was the tension. Everyone in the place, it seemed, felt frozen with fear. But not just any fear. A sense that no one was in control, no one knew what was about to happen, and no one had any idea what to do.

Lone protester in Baltimore

This man stood alone between a line of police officers and a crowd of protesters, telling the protesters over and over “Do not give them a reason.” (Source: http://www.independent.co.uk)

I recalled that tension this week as I watched images from Baltimore. I have more than a passing familiarity with Baltimore, although I have to admit I’ve never been to the part of the city where Freddie Gray lived.

My heart breaks for Baltimore because I know something of the city’s character. It’s a flawed city, to be sure. But its people are strong, determined, and very much bound to their community. (On Twitter, my friend Ugur Akinci called Baltimore “a grand & troubled city,” which I think is apt.)

My heart breaks for Baltimore. And I can imagine the tension the whole city must be feeling. Who’s in control? What’s going to happen? What should we do?

On that day in Detroit, thankfully, the store manager knew what to do. He calmed the man down and resolved the problem. When the man walked out the door, it was like all the air rushed back into the place.

My prayer for Baltimore is that its people, proud and strong and hopefully united in a common cause to fix the injustice that’s been going on for decades, will know what to do. And that they’ll waste no time getting it done.

Postscript: Here’s a New York Times video that gives me hope.

What good technical communication looks like

To mark the fifth anniversary of the Deepwater Horizon oil spill, the Tampa Bay Times published a story containing a set of excellent infographics. Although I’m not usually a fan of infographics, I think this piece stands out as an example of good technical communication.

Image of bluefin tuna with accompanying text

Detail from one of the infographics (Source: Tampa Bay Times)

It’s visually appealing: The artwork is well drawn, it supports the text, and it captures the reader’s interest.

It makes technical content accessible to a lay audience: The tone is professional yet personable. Scientific terms (like flocculated) and concepts are explained neatly. Metaphors, like the “dirty blizzard,” adapt the material to the reader’s frame of reference.

It stays neutral: Deepwater Horizon remains a sensitive, politically charged topic for many. This piece sticks to the facts and lets readers draw their own conclusions.

How could the piece have been even better?

Smoother transitions: The first infographic doesn’t contain introductory text. The regular HTML text — not part of the infographic — serves as an introduction. The other two infographics, Effect on Marine Life and Tracking the Oil, contain their own introductory text. (Tracking even contains sub-sections with more introductory text.) As you read, you might not notice that you’re moving from one infographic (major topic) to another unless you detect a font change. Then, suddenly, you realize that the subject matter has shifted. If the transitions were handled better, and more consistently, the reader would experience a less bumpy ride.

Editing for consistency: A good edit would’ve caught some little things, like quote marks used for “dirty bizzard” in two of the infographics but not in the third, or for “downhill” in just one of them. I’m guessing that the infographics were produced independently, perhaps even at different times, and then pulled together for this anniversary story. If that’s the case, then it’s remarkable how little inconsistency there is.

All things considered, the flaws in this piece are minor and are far outweighed by the strengths. The story conveys useful information in an effective and engaging way. It’s a nice piece of technical communication.

What do you think?

Kudos to Times staffers Cam Cottrill, Steve Madden, and Don Morris.

A victim of its own success

I was surprised to read last week that Atlassian — the maker of JIRA and Confluence — is closing down comments on its documentation.

Picture of a large crowd

What happens when you open up your documentation development process to the crowd?

I don’t use Atlassian’s products. But I know their reputation as a progressive, customer-friendly company. They’ve been ahead of most of their competitors in terms of welcoming customer feedback and thus building a community of users.

So why are they closing down their commenting feature? Basically because it worked too well.

Listen to this, from Nick Doherty, manager of Atlassian’s Information Experience (IX) group:

Committing to moderating page comments creates two huge problems: an ever-increasing amount of comments to moderate and, as a result, proportional overhead on the team. For a company of our size, it just doesn’t scale.

Doherty went on to note that only about 20 percent of the comments received were actually relevant to the documentation. (The rest were tech-support questions, requests for new product features, and general inquiries.) He promised to provide an easy way of guiding people to the right places to make those kinds of requests. And the popular Atlassian Answers portal remains in business.

So what happened at Atlassian? Simply put, Atlassian did everything right: they made it easy to comment, they publicized the commenting feature, their employees were receptive and responsive. The commenting feature proved so popular the company was overwhelmed.

What does that bode for the future of user-generated content? If Atlassian did everything right and the idea still didn’t fly, does that mean it’s impossible? Should we just go back to the old days of living in a bubble, isolated from our customers — perhaps saying “drop us a line, and we’ll respond if we can”?

Atlassian-logoNo and no. We can’t go back to the old days because customer expectations have changed. If we don’t accommodate our customers’ desire to provide feedback, someone else will. Third-party websites and aftermarket books will provide platforms for user-generated content — platforms over which our companies will have little or no influence in terms of managing messages and protecting our brands.

So we have to find a way to make it work. I think that Atlassian has given us a model. I won’t be surprised if Atlassian tweaks things, for example by finding a way to siphon off that 80 percent of irrelevant feedback, and comes back as strong as ever. Or, if not Atlassian, some other forward-thinking company will find the key.

Someone will have to find the key. When we talk about user-generated content, I don’t think failure is an option.

What do you think?

Get the name of the dog

Old-style picture of a news reporter at his typewriter

Yep, that’s me — more or less — circa 1978 (source: crayfisher.wordpress.com)

Take a moment and read this terrific article by Justin Willett, a content marketer who worked in a newsroom for 14 years. (The title, Get the Name of the Dog, harks back to a senior editor who advised reporters to get every possible detail for their stories.)

Willet explains how content creators — and I definitely count technical writers in this group — should think like reporters, especially in terms of honing these skills:

  • Interviewing
  • Research
  • Writing – both the inverted pyramid and the art of storytelling

Along with these skills Willett touches on others like attention to detail, critical thinking, and audience analysis. We need to know who we’re writing for, the context in which they’re reading, and why they’re reading.

Willet’s article resonates with me because I got my start in professional writing as a reporter, and because I’ve always thought that my journalistic experience prepared me extremely well for the career I ended up choosing.

Can you think of other reportorial skills that technical writers should master?

What skills did you develop in another field that have served you well in technical writing?

Estimating #techcomm projects: More science to go with the art

Pig lizard creature from Galaxy Quest film

The pig lizard from Galaxy Quest: With any luck my cost estimate will fare better than he did.

My friend Ralph has been in the technical communication business even longer than I have. When I asked him for some pointers on estimating project budgets, he said without hesitation, “You know, it’s more art than science.”

For me, that phrase conjures the friendly alien in Galaxy Quest who said “the operation of the conveyor [transporter] is much more art than science.” That was just before the pig-lizard creature beamed aboard, inside-out, and then exploded all over the conveyor room. Have you ever underestimated a project so badly that it ended up like the pig-lizard? I have.

Although I know Ralph is right, I still wish we had more science to go with the art. I wish we had a few benchmark criteria that we could use for estimating. What that in mind, I’ve listed a few factors that, based on my experience, influence the cost of a project. I’d like your help to add items to this list.


The most reliable factor, by far, is actual cost data from previous, comparable projects. The trick is in the word comparable: is the new project similar enough to an old one to justify using the old one as a starting point?

There’s also the matter of having accurate data from the old project. We any costs hidden from the project’s final balance sheet — for example, translation costs that were borne by the engineering or marketing department?

For me, it’s increasingly unlikely that I’ll find a comparable project to use as a starting point. More and more, each project seems to be a project unto itself. So I’m left having to consider other factors….
Continue reading

I’ve been leading you on

I want to clear up a misconception. The title of this blog, Leading Technical Communication, has led many of you to think that I’m interested in leadership and technical communication.

That’s only half true. I am a technical communicator. But my primary interest, in fact my life’s passion, is leading (rhymes with sledding): the vertical spacing between lines.

Keep following my blog, and together over the next few months we’ll explore topics like:

  • 3 ways to get the leading out of your cramped content
  • The 6 most common line-spacing errors in B2B marketing
  • Feathering your nest: pay attention to that bottom line
  • 27 fascinating leading facts that hardly anyone cares about
Blog logos that demonstrate leading

A few new logos that I’m considering for the blog

Don’t get me wrong. I’m not just into leading. I care about kerning too, in the same way a basketball fan watches baseball to stay amused during the offseason. I mention those two sports because the playing surface for each one features a baseline.

See how cleverly I turned the conversation back to leading?

Leading (ledding), leading (leeding). It’s a common mistake. And since people so often ask for my views about leadership, I’ll sum them up here. They’re pretty simple:

  • I base all hiring decisions on the line spacing in people’s resumes.
  • The best way to handle disputes is to interject “What about leading?” It deflects the disputants’ attention away from the subject at hand. It also deflects their anger away from each other — and usually toward me. Alas, that’s the cross I bear for being the world’s leading leading expert.

Happy April Fools Day, everyone.