Author Archives: Larry Kunz

About Larry Kunz

I’m a technical communication professional with more than 30 years’ experience as a writer, manager, planner, and information designer. In my paying job I lead projects and perform consulting for clients who want to treat their customer-facing content as a business asset. I teach a course in project management in the Technical Communication certificate program at Duke University. I’ve also developed and delivered courses in structured authoring to internal staff and corporate clients. I’ll be happy to speak at your next event, either in person or over the web, about Tech Comm or any related subject.

Try the knish

It’s a typical New York weekday. The well-dressed businessman, passing a sidewalk lunch cart, says to himself:

Is today the day I'll break down and try a knish? No, not today.

Is today the day I’ll break down and try a knish? No….not today.

A sign of strength

I’m struck by the businessman’s choice of words: break down. Is it really breaking down — is it really an act of weakness — to try new things? Of course not. Changing, and welcoming change, can be a sign of strength.

Professionally, we have to be open to change. While I fully understand the impulse to play it safe, to avoid risk, I can’t imagine where I’d be if I hadn’t welcomed change during my career in technical communication. Well, I can try to imagine: I’d still be writing print manuals for large-systems software, using command-line authoring tools. And I’d be pretty much unemployable.

I knew a programmer who insisted he was a “mainframe guy” and steadfastly refused to learn new operating systems or programming languages. He stayed employed up through the Y2K scare — and I don’t think he’s worked in the field since.

For him, weakness was in not being willing to change.

A sign of even greater strength

If welcoming change is an act of strength, I’ve recently come to appreciate that resisting change, when the change would undermine your values or compromise your principles, is an act of even greater strength.

We now live in a world where people in authority can lie and not be held to account. Where falsehood is presented as truth and truth as falsehood. Where people unabashedly engage in bigoted behavior. In an remarkably short time, the world has changed. These changes, rather than being welcomed, need to be resisted.

Paradoxically, it’s often by refusing to welcome healthy change (a Muslim family moves in next door, for example) that people end up changing in much bigger ways — letting go of their core values, compromising their principles. They become liars, to protect what they believe is being threatened. They become complicit at hiding or distorting the truth. They become bigots, lashing out at anyone who’s different.

The strong person is the one whose moral compass holds steady, who sees change and doesn’t react in fear.

Keeping strong

You’ve probably heard Reinhold Niebuhr’s serenity prayer:

God, grant me the serenity to accept the things I cannot change,
Courage to change the things I can,
And wisdom to know the difference.

To help me navigate today’s world, I’ve updated it:

God, grant me the enthusiasm to accept  change that will enrich me,
Strength to resist change that will diminish me,
And self-awareness to know the difference.

knish

Go ahead. Try one.

Was it a matter of principle for my friend to insist he was a “mainframe guy”? It doesn’t look that way to me. It looks like fear, or stubbornness, or a combination of the two. I’ve tried to learn from his experience, because like most people I’m prone to staying with what’s comfortable.

Strong people don’t do that, though.

It boils down to knowing who you are — knowing your core values and your ethical principles.

Then, when you’re tempted to change in a way that compromises your values and your principles, you recognize the temptation and you summon the strength to resist.

And when you’re presented with something new, and you know that it doesn’t compromise your values and your principles, you can try the knish. And become better for having done so.

Postscript: One of the best changes in my life was moving from the Northeast to North Carolina in my mid-twenties. I have one lingering regret, though: it’s darned near impossible to find knishes here.
Cartoon: Warren Miller, The New Yorker

Photo: Mostly Foodstuffs

We ask the good questions

It started with a simple question. What, I asked the Hardware Test guys, are the power consumption and heat dissipation measurements for the new switch models? I needed that data for the Technical Specifications section of the user guide.

infobooth

Questions and answers in Seoul, Korea (by WordPress user george2008)

To be helpful, I included with my request the chart for the existing models — my way of saying “I need numbers just like these.”

One of the Test guys looked at the chart, paused, and said, “I’m not sure these numbers are so good.”

That sparked a discussion — among 5 of us from Hardware Test, Development, and Tech Pubs — about how the data is collected: is it measured at the power source or at the switch? About how to quantify the data: should heat dissipation be expressed in wattage or in BTUs? About why our customers would want the data: to monitor lab conditions, to plan how best to deploy power supplies. or both.

(That’s right: these mechanical engineers wanted to know not just about feeds and speeds but about the customers’ requirements. Is it any wonder I’m proud to work with them?)

It happens all the time

If you’re a technical writer, you’ve seen it happen too. Your questions open the door to more questions and sometimes to whole new lines of inquiry. Your questions, many times, end up influencing the whole project for good.

Why is that?

For one thing, we’re good at asking questions. My blogging colleague Sharon Burton notes that curiosity is a hallmark of technical communicators, and curiosity often manifests itself in questions. Questions that stimulate thought, questions that force people to reach beyond pat answers, questions that no one’s asked before.

I admit that my initial question about power consumption wasn’t profound. But when the first engineer stroked his chin and paused, I was quick to draw him out, to get him to think out loud and see where the conversation would go.

We’re advocates for our readers, for our audience. We can understand all of the deep-down technical stuff the engineers understand, but we’re not satisfied until we can explain it in terms our readers will find meaningful. Sure, I want to know the amperage reading when all 24 ports are moving data at 10 gigabits a second. But what I really want to know is how a network operator can make decisions based on that information.

We’re persistent. Maybe we’re driven by our innate curiosity. Maybe by our loyalty to our audience. Probably both. Whatever it is, we persist until we have the answers we need — until we can give our readers the answers they’ll need.

Our patron saint is television’s Lieutenant Columbo, who never dazzled anyone with his brilliance but who always persisted, and who always ended up asking the right questions at the right time to crack open the case.

It’s part of our value proposition

I’m proud of the technical writer’s ability to ask good questions. I’m proud that we bring about positive changes, that we contribute value, in this way.

In the lab today, it started with a simple question. The answer turned out to be more complicated than anyone expected. But it was the right answer. It was the best answer.

I’m going to keep asking questions.

Is augmented reality part of technical communication’s future?

While walking my dog last night I came upon a mother and her young son standing on the sidewalk. She was holding her smartphone high in front of her, pointing it toward the western sky.

As I came near she announced, “Mars and Venus.”

skymap_screenshots

The Sky Map map (Screen shots from Google Play)

I learned the names of the planets and stars the old-fashioned way: standing outside on cold nights with my dad, and studying the sky atlas he gave me. But today I guess there’s an app for that. There are actually several apps, as a cursory Google search will attest.

I think it’s cool that you can aim your phone at the sky and learn the basics of stargazing. I think it’s very cool that many of the apps are using augmented reality.

When I got home I downloaded one such app, Sky Map. True to its name, Sky Map immediately gave me a clear, easy to use map of the heavens. I haven’t yet sussed out what all of the icons mean. But I had fun using the Time Travel feature to see the positions of the moon and planets on the day I was born.

Do I sound like a space geek? Guilty as charged.

When it comes to augmented-reality apps, though, I’m still unsure about a couple of things.

No business case?

Number one: the stargazing apps are very low-cost. Many, like Sky Map, are free. So it’s hard to see whether there’s a business case for using AR in training and technical communication.

I write documentation for networking hardware — switches and routers. I can easily imagine how customers would like AR documentation that shows them how to attach brackets to switches and mount them together in a rack. But does customers would like translate to customers would pay for? Or to customers would choose my company over our competitor?

In the absence of clear answers, would my company invest in the tools, time, and training needed to develop such documentation?

Not ready for prime time?

Number two (and maybe this follows from number one): it seems so far that AR is mostly the province of gamers and app developers — not technical communicators or training developers.

skymap_screenshot2

Time Travel, Sky Map style. Recognize the date?

Most of the literature about AR in technical communication is still speculative. An article might say, for example, Here’s what AR is, and here’s how I think it could be applied to tech comm. Or: Everyone loves AR, and tech comm is on the verge of embracing it. I’ve seen only a handful of isolated case studies in which AR actually is being used for technical communication.

One such case study is General Motors’ myOpel app. GM began distributing the app to Opel owners a few years ago. Does anyone know if they’re still doing so? Or if they’ve expanded the idea to other brands? (A quick peek at Google Play reveals that myOpel is still available but it’s getting only tepid reviews.)

So, despite the star-struck articles (one of which — full disclosure — I wrote in 2013), I remain unconvinced.

What do you think? Do the stars say that AR will be a big part of technical communication’s future? Have you done AR work for technical communication or for training and if so, have you succeeded in making the business case for it?

Ethel Payne: You should know her name

Ethel Payne. I didn’t recognize her name. But the cover of James McGrath Morris’s biography, Eye on the Struggle, called her “the First Lady of the Black Press” — a pioneering journalist of the civil rights era. I wanted to learn her story, so I picked up the book.

payne

Ethel Payne (Washington Post file photo)

I learned that Payne was indeed highly influential, reporting on and often playing a part in the big civil rights stories of the 1950s and ’60s.

I learned that Payne made several trips to Africa, believing there was a close connection between the American civil rights movement and the efforts of African nations to gain independence. Late in her life she fulfilled a dream by interviewing Nelson Mandela after his release from prison in 1990.

I learned that Payne’s writing appeared primarily in the Chicago Defender and other newspapers targeted to the African-American community — the “black press.” I’d known that such papers existed, but I’d never read them. So it still didn’t faze me that, even though I knew about Montgomery and Little Rock and Selma, I didn’t recognize the name of a key participant.

Then I learned that in the 1970s Payne worked as a commentator for CBS. I learned that she wrote a syndicated column that was picked up by many of the “mainstream” newspapers. As a result, I realized that I’d probably heard her speak on TV and that there’s a good chance I’d read some of her columns.

Now it bothers me that I didn’t recognize Ethel Payne’s name. Why hadn’t I remembered her? Continue reading

I know it when I see it

Who makes the rules of the internet? Who judges what’s offensive and what’s OK? What are the implications for those of us who create content?

In 1964, the U.S. Supreme Court had to decide whether the State of Ohio could ban a film it deemed to be obscene. Famously, Associate Justice Potter Stewart wrote that while he was hard pressed to define what qualifies something as obscene, “I know it when I see it.”

Where are the boundaries?

ericpetersen_skyscraper_rgb_3000x1500__1_-0-0

Image source: The Verve (Eric Peterson)

The boundaries of offensiveness have always been fuzzy and subject to change. Movie scenes that horrify one audience might not elicit even a blush from another. Books that would’ve gotten me in trouble had they been found in my high-school locker are part of the curriculum today.

Despite the lack of rules, the boundaries are very, very real. Most of us would say with all sincerity that, like Justice Stewart, we know when something transgresses a boundary. There are standards, even if they exist only in our minds and are sustained by our (illusory?) sense of belonging to a community.

The secret rules of the internet

This week I came upon The Secret Rules of the Internet, a long piece that describes the ways in which content is moderated on the major social-media platforms.

To the extent that I’d thought about how moderation works, which admittedly wasn’t much, I never would’ve supposed that:

  • Moderators often work with guidelines that are slapdash and incomplete.
  • Moderators are poorly trained, if they’re trained at all.
  • Moderators are prone to depression and other psychological disorders, largely because their jobs force them to see things they can’t bring themselves to describe to anyone.
  • There are no standards or best practices for moderation; rather, most media companies treat their moderation practices as trade secrets.
  • Moderation is often shoved into a “silo,” segregated from the rest of the company, even — especially — from areas that set the company’s course in terms of legal and ethical principles.
  • Some platforms are better at moderation than others. (The article contrasts Facebook, with its relatively well defined Safety Advisory Board, and Reddit, which has weak guidelines, a small team of moderators, and a reputation for harboring lots of offensive content.)

According to the article’s authors — Catherine Buni and Soraya Chemaly — all of these things are true. Continue reading

Our creative future

ai_oracle

Image source: Oracle

Happy new year. Or, to phrase it differently, welcome to the future.

I’ve just read a couple of fascinating takes on the technologies and the jobs that await us in the not-too-distant future.

Innovations in artificial intelligence

In Big Tech’s AI Predictions for 2017, experts from leading technology companies provide a peek into technology that will arrive in the next couple of years. We’re treated to new advances in voice-recognition technology, new uses for AI, and more. A couple of examples:

“In 2017 there will be a chatbot that passes the Turing test, exhibiting responses so human-like that an average person wouldn’t be able to tell if it’s human or machine.” – Jim McHugh, Vice President and General Manager, NVIDIA

“2017 will see product developers rapidly adopting the latest AI-powered voice recognition technology, [using] speech APIs and tools that are now free to use.” – Adam Coates, Director, Baidu Silicon Valley AI Lab

Reading the article reminds me of my childhood trips to the World’s Fair, where futurists paraded their visions and inspired me to dream of seeing in my lifetime a wonderful, exciting world enabled by technology and human ingenuity.

Tomorrow’s design jobs

The Most Important Design Jobs of the Future lists new jobs that, according to a panel of design experts, will need to be filled within 3 to 5 years.

Some job titles are self-explanatory (though still fantastical), like Augmented Reality Designer and Human Organ Designer.

Others, like Cybernetic Director (responsible for the creative vision and execution of highly personalized media services) and Fusionist (envisioning and creating cross-disciplinary links between art, engineering, research, and science), reflect new directions for technology and for the way people will use it.

Technical communication blogger Danielle Villegas (TechCommGeekMom) laments that she feels unprepared for the jobs of the future. “How does one train or learn [for] these kinds of positions,” she asks, when it’s hard enough keeping up with the technologies and opportunities that exist today? Continue reading

In praise of the ebullient worker

1985-ozzie-smith

Ozzie Smith doing his thing at the 1985 World Series (source: Sports Illustrated)

Have you ever worked with someone like Ozzie Smith?

Before really big games, the Hall of Fame shortstop delighted his fans and teammates by doing backflips on the field. In every game he played, his gestures and body language made it clear that he was enjoying himself. His joy spread to everyone who watched him — except, maybe, fans of the opposing team.

Have you ever worked with someone who delights in their work and spreads joy through the workplace? If so, you’re lucky. There are far too few people like that. I call them the ebullient workers.

Just to be clear, I’m not talking about:

  • The clowns, who love jokes and pranks but never take anything seriously and can’t be counted on to pull their weight. A clown’s act might be appealing at first, but before long it becomes stale — no matter how good the jokes are.
  • The showoffs, who take delight in their work but at the expense of rival workers or even teammates. The showoff’s delight isn’t really in their work — it’s in proving that they’re better than everyone else. Instead of sowing unity, showoffs sow division.

If you’re an ebullient worker

Good for you. Keep it up. You might ask “Keep what up?” because your ebullience just comes naturally. You have a rare gift of bringing light and life to the workplace. Don’t let anybody or anything — frowning colleagues, disapproving bosses, a stifling corporate culture — extinguish it.

Sometimes, unfortunately, that means that you’ll need to find another place to work. That’s a steep price to pay, but it beats losing the passion you bring to your job every day. Continue reading

Living and learning: 2016

Merriam-Webster picked surreal as its 2016 word of the year, and…yeah. At times this year I’ve felt like Alice in Wonderland, and I’ll bet you have too.

One thing remains as true as ever, though: if you’re not learning, you’re not living.

Here are some things I learned this year:

The future is technical communication

screen-shot-2016-02-25-at-6-07-54-pmTechnology is moving forward at breakneck speed. People want technology. People have different learning styles.

Who can deliver the information people need to make use of, and enjoy, the technology that’s all around them? Technical communicators, that’s who.

That’s the gist of Sarah Maddox’s keynote speech at tcworld India 2016.

I think Sarah is saying that we need continuously to hone the technical part of our job title, while not neglecting the communicator part. And I think she’s absolutely right.

We care a lot about our professional society

STC logoSome of my most popular posts this year dealt with the Society for Technical Communication (STC) and its role in a changing world. How can STC remain relevant when the traditional roles of professional societies are changing? How can it serve a community that’s growing ever more diverse, in terms of the kinds of work we do?

As 2017 begins, STC is looking for a new CEO. Whoever gets the job, and whatever things they choose to prioritize, I hope they’ll appreciate the passion and dedication of STC’s members.

DITA isn’t cheap (but it’s still worth the cost)

DITA logoEven as more organizations embrace DITA for developing their content, we hear that DITA is complex and hard to learn. Overcoming DITA’s acceptance hurdles was one of my most commented-on blog posts this year, as was my plea for greater sensitivity to the writers’ learning curve.

Yes, DITA is powerful. But it didn’t get that way by being simple. I’ve come to appreciate that writers need time to absorb the underlying principles, which happen to align closely with the principles of good technical writing, and they need time to learn the how-to aspects as well. It’s time well spent, I think.

A leader is a storyteller

monsterWe saw it in this year’s political news: for better or worse, people are drawn to the leaders who tell the best stories.

As technical communicators, we’re by nature good storytellers.

Does it follow, then, that technical writers have an edge when it comes to being good leaders? I think it does.

Don’t take things too seriously

The year truly has been surreal. Many of our deeply held beliefs — about leaders, about governments, about the course of history — have been challenged if not overturned.

Yet my most-read post in 2016, by far, was a collection of jokes. That taught me not to take things too seriously, and especially not to take myself too seriously.

It reminded me that we’re all human beings. We all need to connect with each other and, sometimes, share a laugh.

I hope I’ve connected with you, at least a few times, in 2016. I hope we’ll continue to connect in 2017. And even share a laugh or two.

Related: Living and learning: 2015

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