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.

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.

Recommended: Dreyer’s English

(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.

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

What 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.

Carrying the earth on our shoulders

At last week’s STC Summit, I attended a couple of presentations that probed the same question. It’s an old question, but it’s still a thorny one.

I used to see this guy on childhood trips to New York. Now he reminds me of my Tech Pubs colleagues.

How can we integrate content into a unified presentation when the content comes from all over the place? When different teams — communication specialists and nonspecialists — are creating content using different tools and different styles, often with different objectives in mind, how can we present it to customers as a unified whole?

Both presentations showcased successful case studies for integrating content. Both placed the Tech Pubs department at the center of the action. Yet both left me wondering why this whole thing — integrating content produced independently and content produced as part of a collaborative effort — isn’t easier.

How do you know I’m telling the truth?

Deep in the Amazon rain forest, they do a really marvelous thing.

Have I seen it for myself? Well, no. Did I hear it from an eyewitness? No again. Truth to tell, I read about it on the internet.

The Papuri River in South America (photo: Andre Baertschi)

I need to back up and start from the beginning.

Dave Thomas, in a recent article titled The Revolution Will Have Structured Content, describes how the language of a culture will reflect whatever values the culture finds most important.

Thus, for example, “if we require Mr., which says nothing about marital status, before a man’s name but either Miss or Mrs. before a woman’s name, we are saying that the most important thing to know about that woman is her marital status.” And that’s why, over the last half-century, the use of Ms. has become prevalent.

A grammar based on evidence

Now, Thomas asks, what if a culture placed a high value on truth? Would its language evolve a grammar that would help a listener to evaluate the veracity of a given statement?

Policing the public square

No doubt you’ve seen the news. Facebook CEO Mark Zuckerberg has gone up to Capitol Hill this week to answer questions from several different Congressional committees. They want to know what Facebook is doing about privacy breaches and interference by foreign actors.

In his prepared testimony, Zuckerberg said:

“It’s not enough to just connect people, we have to make sure those connections are positive. It’s not enough to just give people a voice, we have to make sure people aren’t using it to hurt people or spread misinformation. It’s not enough to give people control of their information, we have to make sure developers they’ve given it to are protecting it too. Across the board, we have a responsibility to not just build tools, but to make sure those tools are used for good.”

Mark Zuckerberg and assistant Andrea Besmehn arrive on Capitol Hill (photo source: NPR)

So, as NPR’s Camila Domonoske points out, Facebook now admits that it’s a content publisher, not just a technology platform on which other people create content. That’s big news.

Here’s even bigger news: