Category Archives: Technical communication

The best gifts I’ve received

Gift-wrapped packages

I like gifts. Just don’t say “free gift.” That sets my teeth on edge.

In this gift-giving season, I pause to recognize some of the people who’ve given me gifts during my career. There are lot of them, but these stand out.

The manager who invited me to bring any and every problem to him — as long as I also brought a solution. My solution might not, in the end, be the solution we chose. But it started our conversation, and — most important — it got me focused on fixing, not dwelling on, my problems.

The public-speaking trainer who, early in my career, assured me that my audience wants me to succeed — not make mistakes they can pick apart. To prove his point, he asked me what I want from a speaker when I’m a member of the audience.

A colleague’s advice that speaking or teaching is a form of gift-giving — that my words are something of value, a gift for my audience. People like to receive gifts, he said, and you should enjoy giving them too.

Plastics scene from The Graduate

Just one word: DITA

The team-lead, at IBM in the early 1980s, who encouraged me to learn a precursor of DITA that was just coming into use. Think of Benjamin Braddock and “plastics” — except that I took it to heart. I embraced the idea of structured authoring before I could become too set in my ways as a technical writer. I’ve benefited ever since.

Finally, numerous managers who saw farther than I could and helped me prepare for what was coming — whether it was a new technology or a department-wide layoff. And other managers who took a chance on me, and then — when I didn’t get it right the first time — took a second chance.

I’m grateful to all of them.

I’d like to hear about gifts you’ve received that helped you in your career. Share your stories in the comments.

Advertisements

An image with an impact

If good writing is the foundation on which technical communication is built, then visual elements provide the curb appeal.

Even though most of my training and experience are in writing, not illustrating, I’m keenly aware of the huge effect — for good or ill — that visuals can have on content.

I pay close attention to how the artist chooses to present data in maps and graphs, because that choice can strongly influence the reader’s perception.

I like to spotlight images that are informative and well-executed — like the map in ProPublica’s story on last summer’s Houston floods and the Tampa Bay Times‘ 2015 infographic about the Gulf of Mexico after the Deepwater Horizon oil spill. (Unfortunately, the Times has removed the infographic from its site, but a small piece of it survives in my post.)

Then there’s the recent op-ed by the New York Times‘ Nicholas Kristof on gun violence in the U.S. In an article full of bar graphs and maps, one image in particular made my jaw drop.

Wishing to point up the lack of research into gun violence, compared with research into diseases like cholera and diphtheria, Kristof had a Times artist compare two data points for each problem: number of people affected and number of research projects funded by the National Institutes of Health over the 40 years ending in 2012.

As you scroll down, try to set aside your political views — whether you’re pro- or anti-gun control — and evaluate this image on how effectively it delivers its message.

graph juxtaposing 4 million gun-violence cases and 3 research grants

I’ve seen very few images that delivered their messages so startlingly, so resoundingly. The numbers are impressive, but the huge red circle and the three tiny boxes thunder out the message: gun violence, while a serious threat to public health, is woefully under-researched. (Kristof says that’s because of lobbying by opponents of gun control.)

Feel free to disagree with the message. But don’t tell me that it wasn’t delivered effectively.

Why do people mangle the language?

confusedAt the recent Australian STC conference, Neil James was asked why people write Manglish, or mangled English. I very much like what he had to say.

(As quoted in Sarah Maddox’s blog, ffeathers. Emphasis mine.)

  • At school, we imbibe the notion that complex writing is better writing. Waffle gets reasonable marks, provided it’s elegant waffle.
  • Early in our careers in the professional and technical workplace, mastering and using the technical jargon of our field gives us a stronger feeling of belonging.
  • When we learn the tech vocabulary of a particular industry, it’s difficult to adjust to communicating with a lay audience.
  • Institutional culture reinforces the language patterns. Large organisations move slowly. It’s hard to change their processes. When you do successfully introduce change, the organisation moves steadily along the new path.
  • Language is used as an expression of power. Sometimes, people deliberately use jargon to protect their financial interests or to manipulate public opinion. An example is from the airline industry, when people use the term “loss of separation” of two planes, which means the two planes collided.

What do you think? Have you experienced a “loss of separation” with some mangled English lately? What might’ve caused it, do you think?

Mapping space and time

Earlier this afternoon, you arrived in an unfamiliar city. Now you want to get out and do some exploring. Where’s an art gallery? A bookstore? A coffee shop?

On a display board at a bus stop, you find a map of the city with points of interest marked. With a little effort you find an interesting-sounding gallery and see that it’s eight blocks west.

The map in front of you describes physical space. Wouldn’t it be nice if the map answered one more question: How long will it take me to get there?

You’re looking to take a trip, not just through space, but through space and time.

You need a time map. Peter Liu, whose company is called Mapbox, is working to design one for you.

As Peter points out, time maps aren’t new. He even found one from Melbourne, Australia, that was used a century ago. But today’s software creates lots of new possibilities.

Melbourne time map

Travel times from central Melbourne via rail, 1910-1922 (source: Peter Liu)

Check out Peter’s time maps for yourself. I especially like the one that changes based on whether you’re walking, riding a bicycle, or driving a car.

Maps are one of my favorite forms of technical communication. Maps have been around for so long, however, that it seems like we already know everything there is to know about making them.

That’s why the time map caught my attention: it’s a new way of looking at something old and familiar.

What do you think? Will we see more time maps in the future? Can they change the way we interact with the world around us?

Delighting in our language

Fellow technical writer Tom Johnson has entitled his blog I’d Rather Be Writing.

But lately it seems Tom wouldn’t rather be writing — at least, doing technical writing. In Tom’s words, the day-to-day job of technical writing, especially the plain language aspect, has “removed my ability to delight more in language and to express myself in more articulate, interesting ways.”

Tom describes the essays his wife writes as a student in a Master of Liberal Arts program. She gets to deploy phrases like erstwhile acolyte — phrases that would never find a place in technical writing. For Tom, the thrill is gone. Worse, he says, in both writing and reading he’s lost the delight of learning new words, playing with the language, and “enjoying the eloquence of an author.”

How do I respond to a brother writer in need?

First, by stating the obvious. Erstwhile Acolytes would be a great name for a rock band.

Second, with understanding. Early in my professional life I dreamed of making my living as a “creative” writer. I — and many of my young colleagues — looked at technical writing as a way to put food on the table until we sold that first novel or screenplay. Now, nearly 40 years later, here I am — still working as a technical writer.

But something happened along the way. I came to understand that all writing — including technical writing; maybe especially technical writing — is creative, because problem solving is a creative process. In our case the problem is how to communicate most effectively with the target audience.

Tom mentions the Simplified Technical English (STE) dictionary. Originally developed for the aerospace industry, it stipulates a set of writing rules and a vocabulary of about 900 words. Erstwhile isn’t one of those words, and neither is acolyte. Yet communicating effectively within the constraints of the dictionary is a creative activity. It’s like solving a puzzle.

various kinds of puzzles(Granted, it’s a puzzle in which I reserve the right to change the rules. If I know that the precisely right word happens to be outside the 900-word canon, then dammit I’m going to use that word. Audience trumps guidelines every time.)

So, yes, I don’t get to write erstwhile acolyte in the Installation Manual for E4G Routers. But I get the satisfaction of knowing that I’ve met my audience’s needs. And I’ll shelve erstwhile acolyte until I’m writing for an audience it resonates with.

Which brings me to my last point. Vary your writing by finding different audiences. All technical writing and no play makes Johnny a dull boy. This blog, for example, gives me a platform for reaching a different audience — still professional, but more collegial — than I reach in my day job. Here I can write more expressively and have a little more fun.

So, if you want to recapture the joy of using our language, I’ll suggest to you, as I suggested to Tom, that you try writing for different audiences. Try writing essays or poetry. And each time you write, think of it as solving a puzzle: the puzzle of how to communicate effectively with the audience you’re addressing.

Do you ever find yourself losing your delight in our language? What ways have you found to recapture that delight?

A new vantage point

Around 1610, Galileo Galilei, pointing his newly invented telescope at the sky, became the first person to see bulges on both sides of the planet Saturn. He didn’t know what they were. It took 45 years before another astronomer, Christiaan Huygens, figured out that they were rings surrounding the planet.

For 350-plus years since then, every view we had of the rings came from the same vantage point: from outside.

Until last month. For the first time, the Cassini spacecraft slipped between Saturn and the rings, turned its camera away from the planet, and started taking pictures from inside the rings.

Cassini flying inside Saturn's rings
This illustration is part of a NASA animation that shows Cassini’s trip inside the rings. The inset captures an actual image that Cassini sent back.

Following Cassini’s example, I’ve begun considering how I can look at things from new vantage points. If I’ve always looked at something in the same way, have I really seen it in its entirety? Maybe not.

Here are a few things I’m trying to see from new vantage points.

Mergers and acquisitions

My company, Extreme Networks, has acquired parts of 3 different companies over the past year. As a result, our technical writing team is growing rapidly. New people, with all sorts of different backgrounds, are learning our tools, our workflows, and our corporate culture. A lot of anxiety comes with the experience of being part of an acquisition.

I actually have experience with this. I’ve seen things from the other side of an acquisition. Now is a great time for me to remember how it felt — and thereby to help make it easier for the newcomers to our team.

Starting out

My recent participation in the STC Carolina chapter’s mentoring program has given me a new appreciation for how hard it is to break into the technical communication field — from finding a specialty (software writer, e-learning developer, scientific editor) to creating a personal brand to simply landing that first job.

Colliding worldviews

Look at the current world scene and you’ll see people with fundamentally different worldviews. More and more, those worldviews seem to be colliding — and the more they collide, like particles in an accelerator, the more sparks seems to fly. The greater the differences seem to become.

I’m still trying to grasp that. More important, I’m trying to understand the people whose worldviews are different from mine. If I can understand the people on the other side, maybe we can find something in common that we can use as a basis for moving forward together. Maybe that’s too much to ask. I don’t know. But I do know that talking beats shouting, so that’s what I try to do.

(If you’d like to try, too, Jesse Lyn Stoner recently shared some practical tips for taking a stand without polarizing others.)

Epilog

Cassini has been orbiting Saturn since 2004. On Friday its mission will reach its grand finale when it dives into the planet’s atmosphere. When it transmits its last data from inside Saturn’s clouds — a vantage point no one has ever seen — humankind will gain more knowledge about Saturn’s atmosphere than ever before.

How have new vantage points helped you in your professional life? Can you think of other vantage points you’d like to gain?

Informing the public, responsibly

The recent flooding in eastern Texas has engendered a lot of news articles. This one from ProPublica stands out because, in addition to covering a topic of interest, it has all the hallmarks of excellent technical writing.

Let me tell you why.

The lede is up front and to the point

The headline itself conveys the major points: Houston’s Big Dams Won’t Fail. But Many Neighborhoods Will Have to Be Flooded to Save Them. Then, in three brief paragraphs we learn that people are afraid the dams at the Addicks and Barker reservoirs will fail, which would flood much of the city, but despite their fears the dams are safe.

The map is well drawn and emphasizes pertinent data

You can see at a glance the seriousness of the situation. There are the reservoirs, and there are the built-up areas adjacent to them and sometimes inside them. (Yes, inside them. Developers have been allowed to build houses within the boundaries of the reservoirs, on land that — most of the time — is above water level.)

Map showing Houston reservoirs and developed areas around them

Map source: ProPublica

The critical spillways (pink dots) are a bit hard to notice, but they’re called out in the article text.

The spillways, the reservoirs, and Buffalo Bayou, the critical waterway to downtown Houston, are labeled. Less essential details are not.

Background information is explained succinctly

On the assumption that most readers aren’t familiar with Houston’s hydrologic history, the writers provide brief summary information, at pertinent points in the story, about why the two reservoirs were built and how the dams are supposed to work.

Content is organized logically, in short sections

Each section heading is a question, like

  • What are the Addicks and Barker reservoirs? and
  • Why are the spillways a big deal? And what will the impacts of using them be?

The questions build on each other. And unlike with most “frequently asked questions” pages, they’re questions that people actually would ask.

Then each section answers the pertinent question in a few easily digestible paragraphs.

The writing is direct and in the active voice

Picking a paragraph at random:

As of now, the Army Corps says there’s enough excess water in the Addicks Reservoir that some of it is flowing around (not overtopping) one of the auxiliary spillways. The agency originally thought water might also have to flow around the spillways for Barker Reservoir, but now projects that will not be necessary as long as the weather stays good.

The tone is balanced

The article’s tone is businesslike yet reassuring. It reinforces the headline: although this is certainly a big deal, and although people who live near (or in) the reservoirs are going to experience flooding, there’s no cause for general panic.

It’s written collaboratively

Don’t miss the byline. Four different writers are credited for the piece: Kiah Collier of The Texas Tribune, Neena Satija of The Texas Tribune and Reveal, Al Shaw of ProPublica, and Lisa Song of ProPublica. Perhaps one of them, or perhaps an unnamed editor, deserves credit for pulling together everyone’s contributions into a single, coherent piece with consistent tone, vocabulary, and writing style.

I tip my hat to all of them for providing the public with information responsibly and in the proper context.

Postscript: I’m always happy to call out instances of good technical writing that I see in general-interest newspapers and magazines. (Here’s another example, about a different topic.) Do you know of any examples? Please share them in the comments.

 

It’s not your text

Hey, wow. I was looking on the internet and — what do you know? — I found a list.

Yes, I realize that the internet is full of lists. Many of them exist simply to entice us to click. A few might entertain or inform, and then I forget them in 5 minutes.

A very few are worth recommending. One such is this list of rules for editors, compiled by the Baltimore Sun‘s John McIntyre. If you’re in any part of the writing business, hurry on over to The Sun and take a look.

I lingered long over Rule 4: It’s not your text.

You are in the middle of things. You have a responsibility to assist the writer in achieving their purpose. You have a responsibility to the publication to maintain its standards and integrity. You have a responsibility to the reader, the party most commonly overlooked in these operations, to meet their needs of clarity and usefulness. Your personal preferences are subordinate to these responsibilities.

quill penSo it is with editors, and so it is with technical writers as well. We have a responsibility to the company we represent, to maintain its standards and integrity (to the extent it has them), and to present its products in such a way that our readers can use them effectively.

We also have a responsibility to the reader, to meet their needs of clarity and usefulness. This is our paramount responsibility, because this is the one we have to get right. We might get away without perfectly reflecting the company’s style or brand image, or without perfectly describing the product’s features. But if we don’t meet the reader’s needs, so that they stop reading and walk away (or dial tech support), we’ve failed completely.

stone bridgeI’ve heard the technical writer described as the bridge between subject-matter expert and reader. I used to bristle at that metaphor: I thought it implied a passivity on the part of the technical writer, as if we were nothing more than a conduit carrying information from one actor to another. “People walk on bridges,” I remember complaining.

Now, in my old age, I’m more comfortable with the bridge metaphor. Maybe I have a higher opinion of bridges: some of them are engineering marvels, and even the simplest ones are mighty useful. But mostly, I think, I better understand that it’s not my text.

Yes, I play an important role in the transaction between expert and reader. But it’s not about my personal preferences. If I want my name on something, I should write a novel.

My job is to make the information good, and that’s nothing to sneeze at. But it’s not my text.

Look that up: the lexicographer’s conundrum

Old dictionary advertisement

“The one dictionary that puts your family in command of today’s English”

Some of the best stuff you’ll read on Twitter is the wit and wisdom of Kory Stamper and her fellow lexicographers — including the fresh and very woke tweets from Merriam-Webster itself. Those tweets prove the point that Stamper strives to make in her book, Word by Word: The Secret Life of Dictionaries: that lexicography and lexicographers aren’t as boring as you thought.

Stamper makes her point well, in a distinctively breezy, engaging, and elbow-nudging way. Although a few of her chapters run long, going a little deeper into the weeds than necessary, I recommend the book for anyone who’s interested in writing or language in general.

Old dictionary advertisement

“Accept Nothing Less Than the SUPREME Authority”

The best chapter is the one titled “Marriage,” in which Stamper deftly portrays the tension between lexicographers, who know that their job is to describe the language as it is, and their employers, who for more than a century have touted their dictionaries as the absolute authorities on how our language should be used.

Stamper emphasizes that our language is a river, and lexicographers work tirelessly to discover and track all of its whorls and eddies. It took her weeks, for example, just to update the various definitions of take.

(My use of took in that last sentence is sense 10e of the definition for take, the verb. I haven’t even mentioned take, the noun.)

Yet since the days of Noah Webster, at least, dictionaries have contended in the marketplace by claiming to be authoritative, by insisting that they alone can give you a mastery of words. Funk & Wagnalls, in its pre-Laugh In days, trumpeted that its dictionary contained all human knowledge since the world began.

Old dictionary advertisement

“All human knowledge since the world began is concentrated in this one mighty book”

Even today, Stamper’s own Merriam-Webster displays these words on your browser tab when you display its home page: America’s most trusted online dictionary.

How should we reconcile the difference between the marketer’s insistence on prescribing and the lexicographer’s work of describing — especially in an age when dictionaries rely on online ads, not sales of printed books, to survive financially?

Stamper doesn’t give an answer, and I suppose there probably isn’t one. People expect dictionaries to tell them how to write (and speak), while lexicographers compile dictionaries to reflect what people are writing.

It truly is a question or problem having only a conjectural answer — sense 2a of the definition for conundrum.

Meanwhile, our language flows on, whorling and eddying as it pleases.

Yes, and: Helping you communicate better

When actor Alan Alda signed on to host the PBS show Scientific American Frontiers, in which he talked with scientists about their work, he did what most good interviewers would do. He read up on his subjects and their research, and he prepared a list of questions.

As Alda tells it, the first interviews were dull, dull, dull.

Cover for If I Understood You bookThen he tried a different approach. He did only cursory background reading. He didn’t prepare a list of questions. Instead, he sat down to have a conversation instead of an interview.

In his new book, If I Understood You, Would I Have This Look on My Face?, Alda describes what happened. The scientists, realizing they were talking with an interested layperson, started connecting on a personal level rather than delivering lectures. Alda, able to sense the scientists’ thoughts and feelings in the moment, let the conversation flow naturally and comfortably.

Instead of playing the role of a lecturer to a student, or an interviewee to a reporter, the scientists connected with Alda — and, by extension, with the PBS audience — as people talking with people.

Empathy: the key to communication

Alda’s book bears out a lot of things that technical writers already know. Empathy, he writes, is “the fundamental ingredient without which real communication can’t happen.”

Empathy comes from knowing your audience — whether it’s the person across from you in a coffee shop, an audience in a lecture hall, or a datacenter manager who reads your web page. Empathy comes from knowing who they are, what they’re thinking, and what they’re feeling.

Alda writes, “My guess is that even in writing, respecting the other person’s experiences gives us our best shot at being clear and vivid, and our best shot, if not at being loved, at least at being understood.”

He’s right.

He’s also right when he talks about connecting with an audience: “You make a connection by evoking emotions. A great way to evoke emotions is by telling stories. Stories are most effective when you establish commonality with the listener.”

Alda backs up his experience on Scientific American Frontiers with some impressive scholarship. He talks with an array of experts. (It’s easy to get a meeting when you say, “Hi, I’m Alan Alda and I’d like to chat with you about your work.”) He reports on a number of research projects.

Some of the projects were Alda’s own handiwork. He was and continues to be a guiding force behind the Center for Communicating Science at Stony Brook University. His contributions to the science of interpersonal communication are such that STC (the Society for Technical Communication) named him an Honorary Fellow in 2014.

Inprov: new insights for technical writers

Still, despite all of his scholarship and all of his hard work, Alda’s conclusions come as no surprise to most technical writers. We already know about analyzing the audience, about connecting with readers, and about telling stories.

Where Alda adds real value for me is when brings his life’s work – acting – into the picture. Much of the book describes his experience with improvisation, in which actors create scenes together without a script and without any expectations as to the outcome. Continue reading