Category Archives: Professionalism

40 years in the making

Main entrance to IBM lab

The IBM Kingston lab

40 years ago — on May 29, 1979 — I walked into the IBM programming lab in Kingston, New York, for my first day of work as a technical writer.

I’ve seen a lot in those 40 years. Some things about the profession have changed a lot; some haven’t changed at all.

Audience

The audience has always been the focal point for everything we do. 40 years ago, we paid lip service to that fact. Today we understood that we’re here to serve our readers, but we often struggle with how to do that. Soon it’ll be non-negotiable: If we don’t satisfy our readers, they’ll go elsewhere to get information, and they might even choose our competitors’ products over ours.

Tools

Since 1979, tech writing tools have evolved from literally nothing to the jangle of options we have today. (And the interval, from the first tool to the first job posting requiring that tool, was about 5 minutes.)

But eventually the basic principles behind text editors and graphics programs became well enough established that a writer could move easily from tool to tool. Continue reading

Advertisements

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

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

Your guide to defending the truth

Time cover showing journalists around a tableYou’ve probably heard it by now: Time magazine bestowed its annual Person of the Year award on the Guardians in the war on truth. The award honors Jamal Khashoggi, killed at the Saudi embassy in Turkey, the staff of the Capital Gazette, 5 of whom were gunned down in their office, and other journalists who light a lamp in the darkness.

But defending the truth isn’t just for journalists. You and I, the consumers of content, have a part to play too. As I’ve written, we keep the light shining by

This past Monday, Joy Mayer, director of a research project called Trusting News, posted her own list of ways to, as she puts it, repair trust in journalism.

Mayer does a good job of amplifying my points and adding fresh insights. 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