Category Archives: Technical communication

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

Advertisements

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.

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?

Places_you_go_Seuss

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

Is your child texting about technical communication?

Here’s a quick guide to find out:

stack of dictionariesBRB
Big reference books

TMI
Tagging my index

LOL
Learn other languages

NGH
Need graphic here

TTFN
Try this font now

Quill penIDK
Insert DITA keyword

WTF
Write the facts

ICYMI
I corrected your mistakes, incidentally

TTYL
The things you learn

TL;DR
Technical literacy definitely rocks

FTW
Fantastic technical writing