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:

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:

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.

Scary ideas

Zineb El Rhazoui, a columnist for Charlie Hebdo, recently gave a talk at the University of Chicago. She spoke about living under the constant shadow of death threats issued by the Islamic State.

Judith Shulevitz, in a New York Times article titled In College and Hiding From Scary Ideas, describes what happened next:

During the question-and-answer period, a Muslim student stood up to object to [Charlie Hebdo’s] apparent disrespect for Muslims and to express her dislike of the phrase “I am Charlie.”

Ms. El Rhazoui replied, somewhat irritably, “Being Charlie Hebdo means to die because of a drawing,” and not everyone has the guts to do that (although she didn’t use the word guts). She lives under constant threat, Ms. El Rhazoui said. The student answered that she felt threatened, too.

A few days later, a guest editorialist in the student newspaper took Ms. El Rhazoui to task. She had failed to ensure “that others felt safe enough to express dissenting opinions.” Ms. El Rhazoui’s “relative position of power,” the writer continued, had granted her a “free pass to make condescending attacks on a member of the university.”

Fortunately, other students at the university rallied to Ms. El Rhazoui’s defense. Still, isn’t there something backward about people feeling threatened by ideas, especially when the people voicing those ideas are being threatened with literal death?

Cap and deploma: censoredShulevitz also reports on a dust-up at Smith University over a speaker who refused to use the euphemistic “n-word” in a discussion about Huckleberry Finn. The speaker, Wendy Kaminer, is quoted as saying “It’s amazing to me that they can’t distinguish between racist speech and speech about racist speech, between racism and discussions of racism.”

It’s amazing to me too. Continue reading

An object lesson in damaging your personal brand

Tai Tran, Social Media Marketing Manager at Cal-Berkeley’s Haas School of Business, posted a perceptive article about why Starbucks’ #RaceTogether campaign failed.

Starbucks cups with #RaceTogether written on them

Image source: LinkedIn (uncredited)

You probably heard about #RaceTogether. Designed to stimulate conversation about race relations, instead it touched off a firestorm of social-media derision directed at Starbucks.

Tran says, and I agree, that three factors led to the campaign’s going awry:

  1. Poor brand alignment: Does it make sense for Starbucks, a brand many people associate with high prices and gentrification, to lead a discussion about race relations?
  2. Lack of authenticity: Starbucks asked their employees (“partners”) to do the heavy lifting for #RaceTogether. While they’re expert at making coffee drinks, these “partners” have no special training for facilitating a knowledegeable, nuanced conversation about race. The result? #RaceTogether looked like a simple publicity stunt.
  3. No plan for handling blowback: Soon after word got out about #RaceTogether, customers and others began complaining on social media. Starbucks had no answers. Soon, the Twitter account for Starbucks Senior VP of Global Communications was taken down. It’s hard to believe Starbucks didn’t at least consider the possibility of negative feedback, and that they didn’t have a contingency plan for handling it.

The bottom line: despite good intentions, #RaceTogether damaged Starbucks’ brand — damage that easily could’ve been prevented.

As individuals, we can learn a lesson from #RaceTogether. Everything we publish on the web — an article, a blog post, a comment, a Facebook update — has an effect on our personal brands. Most times the effect is innocuous, but sometimes the effect — for good or ill — is huge. It’s hard to predict when those times will be.

The best policy is to start with a clear vision of your personal brand and what you want it to be. Then publish only those things that fit that vision. Had Starbucks done this, they either would’ve found a better way to achieve their hoped-for outcome or they would’ve realized it was nothing they had any business doing.

What lessons do you see in the #RaceTogether experience?

Time to follow a new technology path?

In his keynote talk at the recent TC World conference in Bangalore, Tom Johnson makes the case for creating customer documentation through the use of modern web-development platforms that treat content as code.

Jekyll software logo

Jekyll (software) Logo – source: Wikipedia

Tom invites us, the Technical Communication community, to get past our fascination with XML, which many web developers regard as dated. Instead, he wonders if the time is right to start developing content on popular platforms like Jekyll.

Tom being Tom, he backs his words with action. He’s about to embark on an experiment in which, using Jekyll, he’ll try to replicate the features of DITA. He describes this experiment in the comments section of the same blog post that contains the recording of his keynote talk.

DITA logoI’m an old Tech Comm guy, more a dabbler than a true programmer, so I’m a bit intimidated by the idea of tossing aside my comfortable tool set for something I’ve never used. In fact the phrase “treating content as code” sends a chill down my spine.

Yet I believe Tom is onto something. At a time when we talk about breaking down silos, about leading the effort to unify content throughout the organization, why would we want to wall ourselves off by using our own specialized, peculiar tool set?

I encourage you to listen to Tom’s talk. Then, I’d like to know:

  1. Whether you agree with him — and why.
  2. If you have experience developing documentation using one of the web platforms Tom is talking about. If so, were you successful? What advantages did you find to using the web platform? Disadvantages? Problems you overcame?

I’m sure Tom would like to hear about your experiences too.

I can’t wait to hear about the progress of Tom’s DITA vs. Jekyll experiment. And I hope we can have a fruitful and sustained conversation in our profession about the pros and cons of using web-development platforms — and of using collaborative approaches like GitHub — for creating documentation.

Five reasons you have to vote in the STC election

Forgive the clickbait headline. But, dear STC member, you have to admit it worked. Here you are reading this page.

STC Election 2015Now that you’re here, without further ado:

  1. In 2012 Ray Gallon was elected to the STC Board of Directors by one vote. That’s right: every single person who voted for Ray had a direct effect on the composition of the Board throughout Ray’s two-year term. Everyone who supported the losing candidate, but who didn’t bother to vote, had a direct effect too. Your vote does count.
  2. In 2011 Tricia Spayer was elected to the Board by two votes¹. That’s just in case you thought the 2012 result was a fluke. A golfer getting struck by lightning while sinking a hole-in-one. No, it’s not like that.
  3. Here are the percentages of STC members who did not vote in the last four Society elections: 81%, 84%, 83%, 85%. In an organization that depends on its members’ participation, that’s shameful. Appalling. Pick your adjective. The only way to change it is for each of you to vote, one by one.
  4. I myself have recited the mantra that every candidate is well qualified, and therefore STC stands to gain regardless of who’s elected. (Sounds like Lake Wobegon, where all of the children are above average.) By expressing that view, perhaps I’ve unwittingly helped tamp down the voting percentages. Why vote, if all of the candidates are equally good? Because every candidate is different. Every candidate comes to the election with their own set of priorities for STC, and their own set of experiences. Take time to learn which candidates’ views and experiences align most closely with your views about what’s best for STC. Then vote for those candidates.
  5. STC shouldn’t be one of those organizations you join just to get the membership card, just to add a line to your resume. It’s an organization where, the more you participate, the more you get back. If you’ve never participated in STC, why not start by casting your vote?

Tell me what you think in the comments. If you’ve already voted, tell me why you did.


Note 1: All election results are published on the STC website. Just search for STC election results along with the year.