Category Archives: Technical communication

They’re coming! Are you coming?

At next week’s STC Summit I’ll present They’re Coming! Combining Teams and Cultures. If you’re coming to the Summit, I hope to  see you in my session on Tuesday, May 22, at 4:00.

M&A: it’s everywhere

graph showing growth in mergers and acquisitions worldwide

M&A activity has increased steadily, both in terms of sheer numbers (blue bars) and monetary value (red line). Source: IMAA

If you work for a company in almost any field, chances are good that you recently went through a merger or acquisition, or that you’ll go through one soon. Research by the  Institute for Mergers, Acquisitions and Alliances (IMAA) shows that M&A activity has increased steadily over the past 30 years, in every part of the world.

They’re Coming! is about the changes in people, workflows, and tools that accompany mergers and acquisitions (M&As).

On both sides of an M&A, fear might drive people to think They’re coming! A bunch of strangers is coming to take away my job or to wreck the corporate culture I’ve enjoyed.

Successful M&As don’t happen automatically. I’ve learned firsthand that they require thoughtful planning and deliberate action. Continue reading

Advertisements

You might’ve heard…

I’m taking a few days off. But please check out my guest post on Amruta Ranade’s blog, in which I describe a few things you might’ve heard about technical writing.

Thanks, Amruta, for giving me the opportunity to contribute to your blog!

Communication and tomorrow’s forecast

clouds

In 1854, John Ball, newly elected to Parliament, stood in the House of Commons to suggest that, just a few years hence, it might be possible to predict London’s weather 24 hours in advance.

He was drowned out by laughter.

Not much more than a century and a half ago, the notion of forecasting the weather sounded preposterous. So let me tell you a story.

Because you’re reading this blog, you probably make your living by communicating. As communicators, we don’t always enjoy the same prestige as scientists, inventors, and the other “movers and shakers” in our world. We might be tempted to think that they’re the ones with the ideas; we only communicate about their ideas. Yet the story of how weather forecasting became reality is a story of communication. Continue reading

When the censors come

Remember when a British Library patron was barred from reading Hamlet because an “overly sensitive” Wi-Fi filter decided the play was too violent?

The press reported the story incredulously, focusing more on the folly of using faulty software than on any actual effort to block people from seeing content that somebody deemed inappropriate.

Even when I wrote about the episode — citing our ethical obligation, as journalists and technical writers, to serve our readers with content that’s truthful and complete — I regarded true censorship as something far away and remote. It happened in places like China, where authorities tried to silence the late dissident Liu Xiaobo. But not here in the democratic West.

That was four years ago. Since then, the faraway threat of censorship has come to our doorsteps. Continue reading

Content questions: Critical Thinking 101

In my first content questions piece, I cited Robert D. Kaplan’s Washington Post article, in which he describes how people use content to distort and deceive — how information becomes misinformation and then the misinformation is amplified.

wolf in a forest

Reader Mark Baker proffered this comment:

This is an old wolf in new sheep’s clothing, but there are so many wolves now, and their sheep’s clothing is such a bad fit that we can always see their paws and teeth sticking out.

I respectfully disagree.

This is not to pick on Mark, with whom — based on his subsequent comments and on other conversations we’ve had in this forum — I agree on most things. But here, at least, I think he understates the problem.

Sure, sometimes it’s easy to spot the content frauds. Just like in Cold War-era spy movies, you knew who the bad guys were because they had Russian accents.

But many wolves are better at masking their true selves. Social media, especially, makes for effective masks. It’s easy to pretend you’re something you’re not.

(It’s been 25 years since Peter Steiner’s famous “nobody knows you’re a dog” cartoon in the New Yorker. How much has really changed since then?)

Exposing the wolves

We try hard to spot the wolves behind the masks. We look for trusted allies who can curate the content we receive. And we instinctively turn toward people who resemble ourselves — our tribe.

That exposes some of the wolves, but not nearly all of them.

To expose some wolves, we need to stop judging their appearance and start judging the things they say (or write).

In other words, we need to think critically. Continue reading

Content questions: a crisis of trust

We’ve been talking about content, about who gets to decide what is and isn’t appropriate, and especially about what happens to the content you publish.

A lot of it comes down to trust. Can we trust the content we encounter? How do we know? And, of course, how can we create content that people will recognize as trustworthy?

Meet the Edelman Trust Barometer. Published by the Edelman research firm, the barometer is an international study that focuses on the degree to which people trust “institutions” — defined by Edelman as government, business, media, and NGOs.

Richard Edelman speaking in the video

Richard Edelman (screen shot from The Battle for Truth)

I don’t think I’m off base if I interchange the term content providers for institutions. After all, the content we consume — the content on which we base our opinions and our worldview — comes predominantly from government, business, media, and NGOs. And the content you create probably falls into one of those categories.

The newest Trust Barometer finds that people’s trust in institutions — or content providers — is dropping precipitously, especially in the U.S.

In the words of CEO Richard Edelman, “the United States is enduring an unprecedented crisis of trust.” Edelman even posted a short video, titled The Battle for Truth, in which he said (emphasis mine):

  • We don’t have shared facts. Therefore, we lack rational discourse.”
  • Silence is a tax on truth, and we have to speak up.”

By speaking up, Edelman means that it’s incumbent on every institution — every content provider — to “fill the void for quality information.” Trustworthy information.

I don’t disagree with him. But I doubt that every content provider is willing or able.

What do you and I, as consumers of content, do then? Continue reading

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.