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.

Welcome to your professional home

Close up of a graduation cap and a certificate with a ribbonThis week brought one of my favorite annual events: the celebration at which the students in our Technical Communication program at Duke University receive their certificates.

This year’s group was especially engaged and astute. Their capstone projects reflected their enthusiasm and skill.

Here’s what I told them during our celebration.

A person who aspires to become a doctor passes through a carefully prescribed series of steps: medical school, internship, residency. An aspiring lawyer goes to law school and takes the bar exam.

But people follow all kinds of paths into technical communication. I majored in the humanities and hoped to be the next Bob Woodward, until I discovered that technical writing paid better than writing news. Your other instructors were researchers, software engineers, and trainers. One even went to school to study technical writing. Each of us followed our individual path until we found our professional home.

You too came to this place from a variety of backgrounds. Your cohort includes an academic editor, a user-interface designer, a couple of teachers. You’ve worked in medical research, medical transcription, policies and procedures. We even have an actor and playwright.

Whether technical communication turns out to be your professional home, or you apply the skills and principles you learned in this class in other lines of work, you’ll always be part of the technical communication community.

It’s a diverse community that lives and works all around the world, encompassing many different disciplines in many different industries.

Despite its diversity, its members share a common belief in providing information — relevant, factual, truthful information — to the people who need it, when they need it, where they need it. That belief drives us to make a positive difference in the world.

The members of our community are also creative, and, in our own way, we enjoy having a good time. In fact, right after this we’ll adjourn to the bar and argue about the Oxford comma. Actually, I’m kidding. We don’t argue about the Oxford comma. Every technical communicator knows that the Oxford comma is indispensable.

How many spaces to put after a period. That’s what we argue about.

Read my message to a previous class from the same certificate program: You’re now a technical communicator.

Is “soup to nuts” what we need?

For almost as long as I can remember, pitchmen (especially on late-night TV) have been selling all-in-one gadgets that slice, dice, puree, and do pretty much everything.

In our world of technical communication we have something similar: “soup to nuts” authoring systems that combine all the major steps of the content workflow under one banner:

  • Creating content
  • Managing content
  • Reviewing
  • Publishing
breakfast_gadget

This is actually a thing — but are you using it in your kitchen? (Source: Nostalgic Electrics)

Vendors have been offering systems like this for several years. The sales pitch is alluring: unify all of your content under the banner of one integrated toolset. Lots of content, a multi-step workflow, and one brand to rule them all.

Yet I don’t think I’ve ever seen a company, or even a decent-sized organization within a company, use one of these single-vendor systems for its entire content workflow.

I’ve used parts of these systems. For example, I’ve used easyDITA for content management and publishing, but not for content creation and reviewing. I’ve used XMetaL, but only for creating and publishing content.

In fact I’ve never used these systems for reviewing. All of my SMEs have said the same thing: “Give me a Word document or a PDF that I can mark up. Don’t make me learn a new tool.”

Do any of you use a single, soup-to-nuts system to create, manage, review, and publish content? If so, I’d like to hear from you. Is it working well for you? How easy was it to set up, get buy-in from content producers and SMEs, and train everyone? Continue reading

Getting the team to play together

Gettin’ good players is easy. Gettin’ ’em to play together is the hard part.
– Casey Stengel, manager of 7 World Series winning teams

hands_unity.pngOur work group had gathered for a morning of team building: a role-playing game in which we’d need to work together to solve a series of puzzles. At precisely the appointed starting time, the facilitator burst in and announced that he’d locked the door from outside and the game would begin.

“But one of our people isn’t here,” someone said. (In fact, the missing member had been delayed by a work-related call and had let us know that she was about 5 minutes away.)

“It doesn’t matter,” the facilitator said dismissively. “The rules are clear. We begin on time.”

“No,” our manager replied. “We wait for her.”

No one else said a word. But it was clear that everyone in the room — except the badly outnumbered facilitator — stood in complete agreement.

If team building was what we’d come for, then mission accomplished.

The facilitator muttered something about deducting 5 minutes from the time of the game, which elicited a collective shrug, turned on his heel, and huffed out of the room.

Soon the last member arrived and the game proceeded. Each of us learned about our interaction styles and about how we function together. But for me the most meaningful team building occurred at the moment we all agreed, with no words passing between us, that we wouldn’t leave a member behind.

That shared experience affirmed what all of us, I think, already knew: we have a strong team. From long experience, I know that strong teams don’t just happen.

What can you, as a manager or as a team member, do to build strong teams? Continue reading

It’s time to vote, STC

In much of the world, including North America, the Society for Technical Communication (STC) is the leading professional society for technical communicators. It sets the pace for information and networking, providing a forum for exchanging news and information among practitioners and academics. Its body of knowledge contains a rich repository of research and best practices in the field of technical communication.

2017_election_header.pngSTC is also an association run by volunteer members. Today through March 10, STC members can elect the next slate of volunteer leaders: a Vice President, a Treasurer, 2 Directors at Large, and 2 Nominating Committee members.

The successful candidates will lead STC for the next 2 years – or, potentially, for 4 years, because the Treasurer and the Directors at Large will be eligible to run for reelection when their terms expire in 2019.

I’ve made the case before for voting in the STC election – and I’ve bewailed the traditionally low rate of participation. Here’s part of what I wrote then:

I myself have recited the mantra that every candidate is well qualified, and therefore STC stands to gain regardless of who’s elected. By expressing that view, perhaps I’ve unwittingly helped tamp down the voting percentages.

Why vote, if every candidate is equally good? Because every candidate is different. Each one comes to the election with their own set of priorities for STC, and their own set of experiences. Take time to learn which candidates’ views and experiences align most closely with your views about what’s best for STC. Then vote for those candidates.

You might never hold a leadership position in STC. Still, I urge you to exercise your right as a member – and as a participant in our profession – to help decide who’ll lead STC into the next decade. Learn about the candidates. Ask them questions in the candidates’ forum. Look for the email from STC containing instructions. Then vote.

This year I have one more favor to ask. I’m running for a spot on the Nominating Committee. I invite you to read my candidate statement, and I’d very much appreciate having your vote.

Timing is as important as delivery

Dear technical writer:

Your content is well-written and accurate. But what happens if you put it into your reader’s hands at the wrong time?

This is what happens.

 oscars17.png

At last night’s Academy Awards ceremony, Warren Beatty and Faye Dunaway came onstage to present the award for Best Picture.

When it came time to announce the winner, the card said

Best Actress
Emma Stone
La La Land

Beatty hesitated. Dunaway read the only thing that made sense in the context: the name of a film, La La Land.

It wasn’t until several minutes later, during the acceptance speeches, that the mistake became known. Beatty and Dunaway had been given the wrong card. The Best Picture winner was actually Moonlight.

Dear technical writer:

You might not be embarrassed in front of tens of millions of people. But when you provide the right content at the wrong time, no matter how good the content is, you’ve betrayed your readers.

As every good actor knows, timing is every bit as important as delivery.

Video source: New York Times

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 a 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