Category Archives: Technical communication

Perfect instructions

They were every technical writer’s holy grail: the perfect instructions.

In October 2018, Ernest Fribjer, a technical writer at Techcomm-R-Us in Dayton, Ohio, received an assignment to write instructions for updating CRM records in SalesForce. A few weeks later, without warning, a series of screams emanated from Fribjer’s cubicle.

“Woo-hoo! I did it! I did it!” Then, gales of maniacal laughter, followed by a thud.

task_topic_crime

Original image source: oxygenxml.com

Other Techcomm-R-Us writers raced to the scene. They found Fribjer slumped over his desk, a blissful smile on his face.

As one colleague started CPR, the other glanced at the computer monitor alongside. “Eeee!” she screamed. “It’s perfect! Perfect!”¬†Pirouetting into the narrow corridor, she stumbled and sprawled onto the floor.

The Dayton medical examiner later found that both writers had died from unalloyed happiness. The perfect instructions had claimed their first victims. Continue reading

Advertisements

Recommended: Dreyer’s English

dreyers_english_cover(Subtitle: An Utterly Correct Guide to Clarity and Style)

If you wanted to rewrite Strunk and White’s The Elements of Style — and who hasn’t wanted to do that? — what would it look like?

Benjamin Dreyer, copy chief at Random House, tried his hand, and the result is a New York Times bestseller. If you write for work or for fun, you’ll love it.

Dreyer’s English is partly a style guide — there are handy, easy-to-reference chapters on, among other things, punctuation, foreign words, and proper nouns — and partly a platform for Dreyer’s witty and well-crafted prose. It’s a 21st century S&W, but with less pomposity and more snark.

Dreyer dispenses much of his wit in footnotes, which leads me to my only criticism of the book. Continue reading

Our identity and our future as technical communicators

I like to say, at the beginning of every new year, welcome to the future.

2019, a brand new space with freshly waxed floors and newly painted walls, awaits our arrival. As we enter in, let’s look around for a moment. Let’s think about what we’ll make of the new year.

Our day in the sun

Start with the 2018 STC Summit, where keynote speaker Carla Johnson called technical communicators “the linchpin between people, information, and technology.”

pencil drawing a bridge between two cliffs

Bridging the gap (Source: eurodiaconia.org)

We’re uniquely positioned, Johnson said, to help our companies succeed by influencing the way they interact with customers and prospects. All because we bridge the gap between, on the one hand, products and technologies, and on the other hand, voice, branding, and messaging.

Pretty heady stuff! If Johnson is right, we technical communicators are about to have our day in the sun. Soon everyone in the organization will look up to us.

Back to earth

Yet, at the same time… Continue reading

Architecting value

A month ago, I got a new job title: Information Architect. I maintain my company’s content infrastructure, training and supporting a writing team that has, through mergers and acquisitions, tripled in size over the last 18 months. I also look to the future, defining strategic goals and figuring out how to achieve them.

In describing my new beat, I told the writing team that I have two priorities:

  • Help the team do their jobs as effectively as possible — by listening to them, by training them in both tools and concepts, and by fixing problems
  • Position our documentation products to provide value to the company and its customers

crane with architectural plansWhat does that look like in real life? Well, the first priority is pretty much what you’d expect. If I’m listening to the team, I know where they need training and guidance. And I try to be responsive when someone has a problem. (I also rely on a couple of colleagues who can also step in and troubleshoot when needed.)

The second priority, for me, is the crux of my job. But, paradoxically, it’s a lot harder to envision. Continue reading

Into our reader’s world

You’ve parachuted onto a random stretch of road. You could be anywhere in the world. How quickly can you figure out where you are?

That’s the idea behind GeoGuessr, a web game that’s occupied some — ahem, too much — of my time lately. You might find yourself on a muddy road outside an Eastern European village, a lonely highway in West Texas, or a scenic drive on the Isle of Skye. (For that one, I guessed New Zealand — exactly halfway around the world. Zero points!)

Technical writers are used to this. We parachute into our reader’s world, and we do whatever we can to orient ourselves. We try to understand their work environment, their background, and anything else that helps us communicate with them.

geoguessr_screenshot.png

A rocky coastline. A car driving on the right. Are you on Vancouver Island? Almost: you’re on the Olympic Peninsula, and that’s Vancouver Island in the distance. (Screen shot from GeoGuessr)

In GeoGuessr, you use whatever clues you can find. The game is based on Google Street view, so you can move back and forth, explore intersecting roads, and zoom in on your surroundings.

You’re looking for clues in topography, road signs (Do you recognize the language? Place names?), vegetation (Tropical? Subarctic?) — anything that would suggest or disqualify a particular location.

As technical writers, we look for clues to orient ourselves to the reader’s world. Continue reading

What’s your type? A guide for the modern professional

Once upon a time, if someone wanted to know you better, they asked for your sign. Libra. Sagittarius. Whatever.

Later, Myers-Briggs types had their day in the sun. You proudly told everyone you were an INTJ. Or an ESFP. (I told people I’m an ESPN: I watch a lot of sports.)

Today, you can use technical documentation types to let others know what makes you tick.

You don’t even have to be a technical writer to play.

You’re a policies and procedures manual if your ducks are always in a row. People might say you’re rigid. But there’s never a situation in which you don’t know exactly what to do.

You’re a chatbot if you accost everyone you meet with “Hi! Thanks for using the sidewalk today!” Your real name is Philomena, but you tell people it’s Amy.

You’re a sales brochure if you’re the flashiest, most flamboyant person at the party. If someone’s looking for depth, however, they’ll have to look elsewhere. Continue reading