Tag Archives: documentation

A visit from St. Techwriter

santaApologies to Clement Moore

‘Twas the night before deadline and all through the lab
Not a snack was uneaten — not even a Nab.

The team all were frantic, like bees in a hive —
In just a few hours the site would go live.

The software was bug-free — well, maybe not quite.
But mostly, we figured, it ought to work right.

The UI was kludgy, with widgets and stuff.
But our tech guys said ship it so that was enough.

The specs had been written, then roundly ignored.
To take time to read them no one could afford.

Ready or not, out the product would roll:
Just barely good enough, that was our goal.

When down by the break room arose such a clatter,
I sprang from my bench to see what was the matter.

Away to the window I flew, scared to death:
Gazed into the darkness and drew in my breath.

lambWhen what did my wondering eyeballs espy:
But a white Lamborghini, and that car could fly.

It circled the lot like a bat out of Hades
And landed right next to my boss’s Mercedes.

Its chrome wheels were shiny; its leather seats, red.
TECHDOCS the out-of-state license plate said.

And then when the driver hopped out from inside ‘er,
I knew I was seeing a technical writer.

His eyes they were sunglassed; his goatee was trimmed.
His cheeks they were shallow; his build it was slim.

His droll little mouth was drawn up in a smirk,
And he carried a laptop — he’d come to do work.

A cup of espresso he held to his lips
And as he strode toward me he took little sips.

When his eyes locked on mine I knew in my heart
That our shiny new product was doomed from the start.

His countenance told me — I couldn’t refuse it —
The product won’t sell if nobody can use it.

hollyThen he sat himself down by the Pepsi machine,
And took out his laptop, his bearing serene.

And wrote, like a sprinter come out of the blocks:
User guide. Help pages. API docs.

More rapid than eagles his writing tools came,
And he whistled, and shouted, and called them by name:

“Now, DITA! Now, oXygen, InDesign, Flare!
Now FrameMaker, RoboHelp, even freeware!”

Then, laying his finger aside of his head,
And giving a nod, to the parking lot fled.

And I heard him exclaim ere he drove out of sight,
RTFM to all, and to all a good night.

A tale told in 5 emails

Act I

coffee-cup-images-016From: Larry Kunz
Sent: Tuesday, December 13, 2016 10:31 AM
To: Robin Bateman, Administrative Assistant
Subject: Coffee machine broken

Hi, Robin.

The coffee maker on the first floor is not working – it reports “error 360.” Can you have someone look at it, please?

This is the machine that brews the pouches.

Thanks,
Larry Kunz
Lead Technical Writer

Act II

From: Robin Bateman
Sent: Tuesday, December 13, 2016 11:35 AM
To: Susie Austen, Acme Coffee Co.
cc: Jack Wheeler, Senior Manager, Facilities
Subject: FW: Coffee machine broken

See Below…

Robin Bateman

[quoted text]
From: Larry Kunz
Sent: Tuesday, December 13, 2016 10:31 AM
To: Robin Bateman
Subject: Coffee machine broken

Hi, Robin.

The coffee maker on the first floor is not working – it reports “error 360.” Can you have someone look at it, please?

[end quoted text]

Act III

From: Jack Wheeler
Sent: Tuesday, December 13, 2016 12:13 PM
To: Robin Bateman; Larry Kunz; Susie Austen
Subject: RE: Coffee machine broken

Did you check to see if its just a jam? Code 360 is a Jam! Check when emptying the Container and see if any packets are stuck in the top or hanging in the machine!? Cmon!

Jack Wheeler

Act IV

From: Larry Kunz
Sent: Tuesday, December 13, 2016 12:25 PM
To: Jack Wheeler; Robin Bateman
Subject: RE: Coffee machine broken

It looks like someone down here figured it out – the machine is working OK now.

WIBNI if the display had said “clear the jam” rather than “call operator – error 360.”

Anyway, all’s well that ends well. And now I know what error 360 means.

Larry Kunz
Lead Technical Writer

Act V

From: Jack Wheeler
Sent: Wednesday, December 14, 2016 8:57 AM
To: Robin Bateman
Cc: Larry Kunz
Subject: RE: Coffee machine broken

Robin;
Please make a laminated sign for each of the Acme Barista Coffee Makers (3 total) indicating the following:

“Code 360 = Jammed pouch in the collection tub”!
Remove tub, empty,
Return tub and system will reset.

Thank you.

Jack Wheeler

Epilog

So another poorly-designed user experience was vanquished — papered over with documentation. And the people rejoiced, because they had their coffee again.

Yet darkness remained over the land.

Exeunt omnes

4 ways to get the most out of your SMEs

For as long as I can remember, and probably from time immemorial, we technical communicators have struggled in our relationships with subject-matter experts (SMEs). Sometimes the results are humorous. Often they’re painful.

Sumo wrestlers in competitionWhen I teach Tech Comm at Duke University, I use this photo of sumo wrestlers to illustrate the struggle. Yet I also hasten to assure my students that it’s not always this way — nor does it have to be.

How can you work with your SMEs to increase the degree of cooperation and limit the pushing and shoving? Here are four principles that’ve helped me. Continue reading

You Have a Right to Ketchup and Salt

Did you see the news story about the Florida chef who refuses to let his patrons put ketchup and salt on their burgers?

If you’re older than 10, says chef Xavier Duclos, you have no business adding any flavoring to the dishes I’ve prepared. I’m the chef. You have to trust my judgment. And that’s that.

burgerIf I were a customer of Mr. Duclos’, I’d beg to differ. Having plunked down $12.95 for one of his burgers (that’s the going rate, according to his menu), I’d say that I’d bought the right to season my food as I liked.

Mr. Duclos has heard that argument, and he rejects it. At best he and I would agree to disagree.

At the same time, I understand where Mr. Duclos is coming from. Continue reading

Granite Countertops and Stainless Steel Appliances

Though it’s probably the most low-key reality show on television, HGTV’s House Hunters has uncovered an overwhelming, and heretofore unknown, passion lurking deep in the American psyche.

Photo of a kitchen with granite countertops and stainless-steel appliancesThe show follows a set formula. A real estate agent asks the home buyers how much money they have to spend and what features they want. Then we watch as they tour three homes, commenting pro and con on each one. After the buyers choose one of the homes, we visit with them post-move and hear them tell us how happy they are with their choice.

The overwhelming passion expresses itself in the features they want. Every buyer, to a man (or woman), wants the kitchen to have granite countertops and stainless steel appliances. Things that look great but are pricey and don’t make the kitchen any more functional or easier to cook in.

Anyway, I got to thinking: What are the granite countertops and stainless steel appliances of technical communication? What are the things that every company, every client, wants to see in their technical and marketing communication projects — regardless of cost or actual business value?

And what should be on everyone’s wish list — but too often isn’t considered? Continue reading

The heart and mind of technical communication

I’ve seen the future. I turned my calendar to today’s date, and there it was.

And when I saw the future, do you know what I realized?

Whoever wants to know the heart and mind of Technical Communication had better learn structured authoring.

I invite you to look into the future too. Just observe what’s going on today. Here’s what you’ll see:

  • Content comes from all over the organization — and sometimes from customers and others as well. Gone are the days when all of the technical content came from the Tech Pubs department. With all of that collaboration going on, we need to have formats in which everyone can contribute content so that it’s easy to mash up together.
  • People read content on all kinds of devices: tablets, smartphones, desktop PCs. If the content can’t at least be adapted to the screens where it’s displayed, it’s of no use. The industry leaders are going beyond adaptive content: they provide content that’s responsive (it changes format to fit the screen) and smart. Smart content changes based on the readers’ attributes: the product features they’ve purchased, their geographical location, and their preferences.
  • Our employers demand content that affects the bottom line. One way to provide bottom-line value is through efficiency: content is developed once and then reused in many different contexts without the need for reformatting.

StructureNone of these scenarios would be possible without structured authoring. Structured authoring allows each piece of content to be tagged for a particular display format or for a particular user attribute, and it allows content to be reused.

Continue reading

Good, not perfect

Like you, I’ve sat through all of those motivational talks. Quality is Job 1. If it’s worth doing, it’s worth doing right. Nothing less than your best.

And I get it. I strive for quality. I try to do my best all the time.

But a funny thing is happening: the definition of quality is changing. Some people are very uncomfortable with that, but that makes it no less true. I wrote about this change a while ago, in a piece called Redefining Perfection.

What’s causing the change? Continue reading

Get the details right: It’s part of your job

Details matter. In life, in art, and in technical writing.

Matt Damon in The Bourne UltimatumIt’s hard to think of three better action movies than the Bourne trilogy, in which the protagonist — Jason Bourne, played by Matt Damon — spends a good bit of time being chased by bad guys. Bourne hopscotches across Europe, eluding his pursuers in Paris, Berlin, Moscow, and London. Finally, Bourne arrives in a city where I know my way around: New York. And that’s where it gets weird. Continue reading

The Hitchhiker’s Guide and today’s technical documentation

Thirty-four years ago this week, Douglas Adams’s classic Hitchhiker’s Guide to the Galaxy was released in book form. While the version that I read was a plain old printed book, the actual Hitchhiker’s Guide—the one that Ford Prefect carried with him—was a pretty cool example of 21st-century technical documentation. Continue reading