Author Archives: Larry Kunz

About Larry Kunz

I’m a technical communication professional with more than 35 years’ experience as a writer, manager, planner, and information designer. In my job at Extreme Networks in Raleigh, NC, I create content for customers and business partners. I'm also part of a team that's always looking for ways to make our content more valuable for our company and our customers. 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.

Content questions: is the human element worth a try?

At a time when the news media is under intense scrutiny, when people struggle to distinguish reliable information from “fake news” from merely biased news, how will we decide — and who will decide:

  • When is content inappropriate?
  • Who controls the content?
  • What if content is used to deceive?

I posed these questions last week, with emphasis on the information, or the content, that we create. And I asked how we — the content creators — will shape the answers.

Answering the content conundrum

Steven Brill interviewed on CNN
Steven Brill, interviewed on CNN on March 4, 2018

Here’s one answer, from Steven Brill, whose Wikipedia page calls him a “journalist-entrepreneur.” Brill’s new project is called NewsGuard.

NewsGuard, whose launch date has not been announced, will try to “help consumers distinguish between sites that are trying to get it right and sites that are trying to trick people.” Those are the words of Brian Stelter, who interviewed Brill for CNN’s “Reliable Sources” earlier this month. Continue reading


Content questions: will we have the answers?

This is about information: who controls its flow, who uses it, and who watches you when you use it.

This is about you. Because you access information — or content — on the internet, and because you probably create it as well.

Will someone have the power to tell you what content is and is not appropriate? Who controls what happens to the content you publish? Will someone use your content to deceive or mislead?

Just this month, 3 news stories have brought these questions into sharper focus. Will we, as writing professionals, have good answers? We’d better, because I don’t know if anyone else will.

When is content inappropriate? Who decides?

Advertisement captioned Don't worry, it's just Twitter

Scene from a recent ad appearing on Twitter’s website and in movie theaters

On March 1, Twitter CEO Jack Dorsey promised to start measuring the platform’s “health” as a first step to freeing users from trolls and propaganda. (Josh Bernoff does a great job of  breaking down the announcement.) Admitting that “we didn’t fully predict or understand the real-world negative consequences” of Twitter’s free-for-all format, Dorsey promises to get busy and fix the problem.

Can he fix it?  Can he put the lid back on Pandora’s box? It strikes me as too little, too late. Continue reading

Lightweight DITA: I’ve seen the light

DITA logo being held aloft by balloons

Lightweight DITA doesn’t have a logo yet. The technical committee is welcome to use this one.

If you’ve taken one of my DITA classes, you’ve heard me extol the power of DITA. One aspect of that power is semantic tagging. In DITA, a piece of content isn’t boldface or italics. It’s a command name. Or it’s a citation to another document. Or it’s the name of a screen (a wintitle, in DITA parlance).

That’s a big selling point for DITA, you probably heard me say. Each DITA element represents what a thing is (hence the term semantic) rather than how it looks. Just think: you can take a big document and generate a list of all the command names, or all the screen names. You can’t do that when you’re just tagging things as boldface and italics.

Turns out there are a couple of problems.

  • First, I’ve never met anyone who wanted to generate a list of all the command names, or all the screen names. While it sounds good in theory, in practice it’s more like a solution in search of a problem.
  • Second, it’s a lot to remember. When is a command parameter a parameter? When is it an option? (DITA has tags for both.) Writers working side by side, writing content for the same help system, might tag the same object in different ways.

Just now, in fact, as I wrote this article, I couldn’t remember the name of the tag for citations. Even though I’m accustomed to using it, I couldn’t retrieve <cite> from my brain. I had to look it up.

Enter Lightweight DITA. Continue reading

Lift a glass for Grammar Day

Grammar Day - Twitter hashtagStarted in 2008 by author Martha Brockenbrough, National Grammar Day is a time to celebrate, and foster an appreciation for, clear writing. It’s observed every year on March fourth — the date that, when pronounced, forms a complete sentence.

A few years ago, Mark Allen — of ACES: The Society for Editing — started a Grammar Day haiku contest on Twitter. This year, tired (I guess) of counting syllables, Mark switched the format to limericks.

The judges must’ve liked my limericks. This one took first place:

“Faulty parallelism, you see,
I eschew most assiduously.”
Thus said Constable Brown
As he sat himself down
And ate limburger, ham, and sipped tea.

And this one tied for second:

Old Frumpengruff’s might’ly perturbed
When he hears that a noun has been verbed.
Though it’s gone on for ages,
Still he (18th c.) fusses and (14th) rages —
In high dudgeon that cannot be (16th) curbed.

I’m delighted and honored, of course. But really, it’s all about celebrating clear writing. Take time to read all of the winning limericks — and take time every day to celebrate our language and deploy it in the name of clear communication.

Launching your technical communication career

Last time I wrote about the places you can go, or the different trajectories your career can take, when you work in technical communication.

But how do you get that first job? What qualifications do you need, and what are employers looking for?

Prompted by interview questions from a Tech Comm graduate student, and based on my experience working in the field and interviewing candidates, here are some thoughts.

montage of album covers from 1979

We listened to different music in 1979, and breaking into the field was different too.

I got my first technical writing job a long time ago — in 1979. One thing I know for sure is that your breaking-in story won’t be the same as mine. Things were a lot different then, and I’m not just thinking about the music we listened to. Companies, having realized that technical people didn’t necessarily make good technical writers, went looking for young writers who weren’t necessarily versed in the technology but who could learn it.

Armed with a double-major in English and philosophy, and having a tiny bit of experience with computers, I landed that first job with IBM.

You won’t have the same experience. Your résumé will need to look a little shinier than mine did.

What are the educational requirements for working in Technical Communication?

Follow-up question: Are certain degrees or backgrounds more sought after by employers? Continue reading

Technical Communication: Oh, the places you’ll go!

A Technical Communication graduate student recently interviewed me for a project she’s doing. She asked great questions, and (with her permission) I thought I’d share some of my answers with you.

What does a career trajectory look like in technical communication?


Your career in Tech Comm, and possibly after Tech Comm, will be uniquely yours — shaped by your interests and talents.

Follow-on question: Is there lots of room for growth, or do people need to transition to management after a certain point?

There is lots of room for growth. Just as people follow many paths into Tech Comm, they find a lot of paths to follow once they’re here.

It’s like Dr. Seuss said: you can go almost anywhere.

Where you go in Tech Comm — or where you go from Tech Comm — depends on what you’re especially good at and what you’re most interested in. Continue reading

Why your idea didn’t fly — and how you can give it wings

Roseate Spoonbill in FlightRemember that great idea you had at work? You knew it would make a huge difference for the company and its customers, that it would pay dividends long into the future.

You pitched it to your boss, or to the C-suite. You put everything you had into it. But they just yawned. Nobody caught your enthusiasm. Worse, when a different, shiny idea caught their eyes, they forgot all about your idea and backed that one instead.

What happened?

Seth Godin provided some answers in his blog this past Super Bowl Sunday. Seth examined why cities spend hundreds of millions on stadiums while projects with a better return on investment — like building roads, improving education, or investing in technology — go wanting.

Learn the dynamics of corporate decision making

Seth sees 5 dynamics at play in decision making at the city or state level. I’m convinced that they also bear on your situation at work.

  • The project is now. It’s yes or no. There are no subtle nuances, no debating the pros and cons for years. We either build the stadium, or our team moves to Vegas.
  • The project is specific, easy to visualize — in contrast with, say, “investing in technology,” which each person is likely to visualize differently.
  • The end is in sight. When you build a stadium, the stadium opens and games are played. With other projects, it’s often harder to visualize the end state.
  • People in power and people with power will benefit. Enough said.
  • There’s a tribal patriotism at work. “What do you mean you don’t support our city?”

So what was your idea? Were you proposing that the writing team embrace structured authoring? Did you want the company to adopt a content strategy?

Why did your bosses toss your idea aside? Maybe you didn’t frame it in a way that took the 5 dynamics into account.

Make your idea fly

How can you improve your odds when it’s time to sell your next idea? Ask yourself these questions.

  • Is it clear cut? Can I create an unambiguous, shared vision in everyone’s mind of what will happen if my idea is adopted — versus what will happen if it isn’t?
  • Can they visualize the results? It might help to tell a story: meet Joe, who just bought our product. Here’s how my idea will improve his life and turn him into a more loyal customer. Or here’s Sally in Tech Pubs, and here’s how she’ll be able to create better content for Joe and others like him.
  • Is the end in sight? Can I describe what the results will look like in a year, or in 2 years? Or am I trying to sell something that brings only gradual improvement? Similarly, can I describe the win criteria: what specific things need to happen for this project to be measured as successful?
  • What’s in it for the executives? This might go against my altruistic nature, but the bosses won’t really listen (although they might pretend to) unless they see some benefit, tangible or intangible, for them.
  • Am I appealing to company spirit? Can I paint a picture of customers waving banners with the company logo, or of the CEO on a stage talking up this idea before a cheering audience?

Try framing your next idea around these dynamics, and you might see a better result. Because people are people, whether they’re a city council or the C-suite at a corporation.

Don’t give up

anoseate Spoonbill, Birding Center, Port Aransas, TexasYou’re probably thinking: my idea can’t score on all of these criteria. By necessity, it’s a long-term solution with no clear-cut success criteria. Or it addresses issues that are internal, “under the hood” — nothing that the CEO would ever talk about onstage.

In that case, go ahead and pitch your idea anyway. Just be aware of the forces that are at work, and be willing to address them. “I know this isn’t something we’ll be able to tout to our customers. But you (Mr. or Ms. CEO) will have the satisfaction of knowing that you’ve made your employees happier.”

Seth, unfortunately, used the word losers in the title of his post. He was saying, I think, that basing decisions on those 5 dynamics is a losing proposition — that cities would see better outcomes (better infrastructure, better education, better quality of life) if they could get past the limitations imposed by the 5 dynamics.

I look at it differently. I prefer to say that Seth has shed light on some basic aspects of human nature. Rather than simply abandoning our less-than-shiny ideas, we can succeed when we understand those aspects and turn them to our advantage.

What do you think? Has Seth given you a way to bring your ideas to fruition, or has he convinced you that your ideas will never gain traction?

Can you share a story of when you got an idea approved by appealing to these aspects of human nature?

Is your child texting about technical communication?

Here’s a quick guide to find out:

stack of dictionariesBRB
Big reference books

Tagging my index

Learn other languages

Need graphic here

Try this font now

Quill penIDK
Insert DITA keyword

Write the facts

I corrected your mistakes, incidentally

The things you learn

Technical literacy definitely rocks

Fantastic technical writing

Don’t twist the prose

It’s never too early to plan for next year’s gardening. I just got a new pair of pruning shears, and on the back of the package I found these illustrations:


….accompanied by these instructions:

Don’t twist the scissors in use. If the scissors are in the city Figure C in the way the clock pointer, the two shear bodies will squeeze each otherDamage: if it is twisted to the look of the clock in the opposite of the A, the time of the clockWill produce a gap between the two sides of the plane, and can not ensure smooth trim. Correct useShould be shown in figure B.

Yeah. Wow.

I was tempted to laugh and roll my eyes, and I confess that maybe I did. A little.

But it’s also worth pausing to make a few points — because someone wrote this, honestly thinking they were conveying useful information. Nobody sets out to make their readers’ eyes roll. So what happened here? Let’s think about it.

Don’t overthink

First, I’m pretty certain that the writer, despite the best of intentions, overthought the whole thing. Here’s what they wanted to say: For a smooth cut, always cut straight on. Don’t rotate the shears to the right or left.

But, anxious to make sure no one would misunderstand, the writer inserted cross-references to the pictures and added the convoluted text about what happens if you turn (twist) the shears clockwise or counterclockwise. The added detail, rather than clarifying, only muddled things.

My copy often goes from simple to complex, just like this writer’s. Then, after setting it aside for a little while, I can come back and make it simple again.

Translation matters

Then, when you’re writing content for translation, be sure it’s translated by people who know both the source and target languages. It sure looks like this company cut corners when it came to translation. (Maybe they twisted their shears counterclockwise while cutting. Who knows?)

I’m certain that this copy looked a lot better in the source language than it does in English.

Also, when writing for translation, be sure the writer and the translator are working with the same authoring tool. It’s likely that those crashed-together words, like otherDamage and clockWill, resulted from a writer saving the copy in one tool and a translator opening it in another.

Verify, verify, verify

The manufacturer knew they’d be selling their product in a large English-speaking market. Wouldn’t it be nice if they’d usability-tested their instructions — or even if they’d simply verified them with one English speaker?

Perhaps it seemed like an unnecessary expense, or too much of an inconvenience, to verify the instructions. Or perhaps someone simply said We don’t care — just ship it.  Whether that decision will have negative consequences, in the form of damaged customer loyalty or decreased sales, I don’t know. (Very possibly it won’t, which is why someone said We don’t care.)

The decision certainly has resulted in embarrassment for the manufacturer. Can you put a cash value on that?

Reaching your audience through empathy

On Tuesday, January 23, I’ll give an online talk — along with my colleague Christina Mayr — about empathy and how you can use it to connect technical documentation with its audience. Our talk is part of the “Writing Well” conference.

I hope you’ll consider joining us.

Our talk


In the mirror exercise, you and another actor (think: your reader) follow each other’s moves (credit:

Audience analysis is at the heart of what technical writers do. But what makes an audience analysis truly successful? Empathy. Customer empathy spans more than customer service; in fact, it’s most needed long before a user even calls for help. By employing empathetic techniques – for example, monitoring customer support cases to find pain points and improve documentation to address them – you help your users  trust your documentation and seek it out before calling customer support.

Our talk, Improve Documentation Usage with Customer Empathy, will show you how to acquire user empathy and effectively create empathetic technical information. It will discuss several empathetic techniques you can use in your organization to start writing with a better understanding of your users’ pain. We’ll also discuss the case studies, collaboration, and user outreach Extreme Networks performed and the results of these activities.

The event

IDEAS conference logo
The “Writing Well” conference is a two-day, online event that’s put on by CIDM, the Center for Information–Development Management. CIDM brings together managers in the field of information development to share information and new ideas.

The “Writing Well” conference invites you back to basics as we explore what defines good documentation in today’s structured, topic-based environment. What does it mean to write well? What characteristics predict whether or not content will be usable and understandable? Where should we be spending our time? What strategies help authors produce content that users willingly turn to first?

I look forward to connecting with you there.