Category Archives: Media and technology

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

Read this, but watch out for the side effects

Have you heard about the fastest growing job market for technical writers?

Cialis ad with couple in bathtubs

Oh, and if you read this blog in the bathtub, be careful. You could slip and fall.

If you can write the lists of side effects and disclaimers in pharmaceutical advertisements, you’re in high demand. I mean, you must  be in high demand, based on the sheer number of ads I see that promise to cure everything from diabetes to depression to, um, other things.

In keeping with the spirit of the times, here are the particulars about the blog you’re reading. At the bottom of the page, I’ve provided annotations to give you all the training you need to enter the exciting world of medical disclaimer writing.

Do not read this blog while operating heavy machinery, while trapeze-walking across Niagara Falls, or while performing brain surgery..

Do not read this blog if you are a man who is pregnant or about to become pregnant, if you are taking certain [1] enzyme inhibitors, or if you’re just plain feeling inhibited.

Side effects can include drowsiness, nausea, and sudden snorts of laughter. Some severe reactions, including blurred vision and decreased appetite, have happened [2]. Rare but serious side effects, including some fatal events [3] have also been reported [4].

Tell your doctor if you experience memory loss, seizures, hives, and sudden unexplained loss of body parts. They don’t have anything to do with this blog. But you should tell your doctor anyway, because — yeesh — they sound pretty bad.

Happy reading, and best of luck in your new career.


  1. Certain ones. We don’t know which ones. Just trying to avoid liability here.
  2. Have happened: The perfect phrase for disclaiming any and all responsibility for anything at all.
  3. I’m preparing a conference presentation called Pharmaceutical Advertisers’ Euphemisms for “You’re Dead.”
  4. Have also been reported. Sharpen your passive-voice skills with this liability-evading construction.

Questions from the old year, questions for the new

Looking back over this blog’s performance in 2017, I see a pattern. The 3 most popular articles, in terms of page views, were ones that posed questions. The questions I asked in 2017 are still worth considering today.

Is augmented reality part of technical communication’s future?

While AR is popular for gaming, I asked, can it become a viable platform for technical communication? Nearly a year after I wrote the article, I still don’t see much enthusiasm.

screen shot of a sky map appThere are a few popular low-end AR apps, like the stargazing apps I mentioned in the article. Susan Carpenter, in a comment, envisioned using AR for museum interpretation.

But it’s still hard to see a business case for AR in mainstream product documentation. General Motors, attempting to break into this market, deployed its myOpel app a few years ago. While the app is still available, it’s getting only tepid reviews and it doesn’t seem to be spawning imitators.

Why is it so challenging to apply AR to product documentation? Partly, perhaps, because it’s so hard to know exactly what the user is doing — and trying to do — when they access the documentation. Mark Baker pointed that AR will work only if we can maintain our focus, remove distractions, and not introduce new distractions by, say, cluttering the user’s field of vision with “dashboards” full of irrelevant data.

As we turn the calendar to 2018, the vision of AR for technical communication remains gauzy, maybe somewhere in distant the future but not yet coming into focus.

Is “soup to nuts” what we need?

When I posed this question, I was thinking of authoring systems that combine under one banner all of the major steps of the content workflow:

  • Creating
  • Managing
  • Reviewing
  • Publishing

Vendors have been pitching these kinds of systems for a while. But I questioned whether very many real-world content-development teams were buying and using them.

Since I wrote that piece, my company has invested in one of those “soup to nuts” systems. We’ve begun using it to create, manage, and publish content — but not to review it. Just as I said back then, our subject-matter experts still prefer to mark up drafts using a familiar format like Word or PDF.

It’s too soon to tell whether our soup-to-nuts system will, as I feared, actually hinder cooperation and collaboration with other parts of the company. Service and Marketing, for example, use tools and processes that don’t play well with our the soup-to-nuts system we’re now using in Information Development. How big a hurdle will that prove to be?

People who commented on the article expressed skepticism, based on their own experience, about whether soup-to-nuts can work. One correspondent, however, reported being very happy with a tool I hadn’t considered when I wrote the article: Atlassian Confluence.

Will you still need me? (STC at 64)

Sgt. Pepper album with STC logo addedDuring the last Summit conference — and as Liz Pohland took the reins as STC‘s new CEO — I invoked a Sgt. Pepper song to explain why I thought STC, then marking its 64th anniversary, remains relevant in the 21st century.

I said that STC — which for decades has billed itself as the world’s largest professional society dedicated to technical communication — has stayed relevant by:

  • Providing a solid platform for networking and information exchange
  • Curating a body of knowledge
  • Connecting practitioners with educators

To stay relevant, I said that STC must:

  • Reach across to professionals in fields that involve content creation but that don’t necessarily fall under the rubric of technical communication
  • Make newcomers welcome and help them find their place in the organization
  • Find new ways to attract, train, and energize volunteers — because volunteers are the lifeblood of STC
  • Build its certification program into something that’s valued by practitioners and their employers — a process that’s likely to take a long time
  • Continue to operate as a worldwide society, retaining its place at the table alongside organizations like tekom in Europe

Now, in 2018, STC is spotlighting its age: its next conference is billed as the 65th Anniversary Summit. I think that its strengths, and its challenges, are much the same as they were in 2017.

What do you think — about STC, about soup-to-nuts systems, or about augmented reality?

What questions do you think our profession will need to focus on in 2018?

7 words you can’t say at CDC

According to its mission statement, the Centers for Disease Control and Prevention (CDC), an agency of the U.S. government, “increases the health security of our nation.”

CDC logoIt does so primarily in two ways: researching diseases and their cures, and informing the public about its findings. For example, you might remember CDC’s role in warning citizens about the zika virus in 2015.

A few words might be missing

Soon, however, when you get information from CDC, a few words might be missing. Reportedly, senior officials within the Department of Health and Human Services recently decreed that CDC and other HHS agencies are forbidden from using 7 words in their official budget documents.

(This is a developing story. On Sunday, CDC Director Brenda Fitzgerald called the report about the 7 words “a complete mischaracterization of discussions regarding the budget formulation process.” The word mischaracterization leaves wiggle room: it’s reasonable to assume that there was discussion about avoiding certain words — even if it wasn’t an all-out ban.)

George Carlin with the 7 words superimposed on his photo

Credit: Scott Smith (@stampergr) on Twitter

Here are the 7 forbidden words:

  • vulnerable
  • entitlement
  • diversity
  • transgender
  • fetus
  • evidence-based
  • science-based

What does it mean when words become non-words? As anyone who’s read George Orwell’s 1984 knows, it’s an attempt by those in power to impose control.

They know something I’ve known throughout my writing career: words matter. A lot.

By changing the words in the conversation, do the people in charge at HHS think they can change reality? No. I don’t believe they’re that foolish. Not all of them anyway.

They can’t change reality, but they can change the way in which reality is discussed. If they change the terms of the discussion, they can influence the way people think.

When nothing can be described as evidence-based or science-based, there’s no longer a need to question a finding that’s unsupported by evidence.

When transgender is stripped from the vocabulary, they can more easily dismiss the health needs of thousands of our fellow ci.tizens.

When they stop saying vulnerable, it’s easier for them to overlook human beings who are vulnerable and who need help.

The Florida tides

It brings to mind what happened in Florida a few years ago. The state’s Department of Environmental Protection ordered its staff not to use the terms climate change and global warming in any official communications, emails, or reports.

This despite the fact that, according to a New York Times article, “when many cities in Florida flood, which can occur even without rainfall during the highest tides, fish swim in the streets and people wade to their cars.”

But the nabobs in the Department of Environmental Protection, even as the bottoms of their trousers get soaked, need not trouble themselves with the thought that this is anything more than a random natural phenomenon.

What can we do?

There’s a lot at stake here. Although it’s tempting to smirk and roll our eyes, we mustn’t dismiss this as mere bureaucratic foolery. Instead, we need to call it out for what it is: an attempt by those in power to impose control.

Be wary of gaslighting — of any attempt to change the way reality is perceived. Don’t let Why don’t we talk about x any more? turn into X never happenedAll of us share a duty to know the truth and hold fast to it.

Finally, even if HHS won’t use those words, by golly we can use them. And we should. Question what this government tells you — and don’t be afraid to answer back, What about the vulnerable ones? What scientific evidence do you have for this?

Never let them forget that words matter.

An image with an impact

If good writing is the foundation on which technical communication is built, then visual elements provide the curb appeal.

Even though most of my training and experience are in writing, not illustrating, I’m keenly aware of the huge effect — for good or ill — that visuals can have on content.

I pay close attention to how the artist chooses to present data in maps and graphs, because that choice can strongly influence the reader’s perception.

I like to spotlight images that are informative and well-executed — like the map in ProPublica’s story on last summer’s Houston floods and the Tampa Bay Times‘ 2015 infographic about the Gulf of Mexico after the Deepwater Horizon oil spill. (Unfortunately, the Times has removed the infographic from its site, but a small piece of it survives in my post.)

Then there’s the recent op-ed by the New York Times‘ Nicholas Kristof on gun violence in the U.S. In an article full of bar graphs and maps, one image in particular made my jaw drop.

Wishing to point up the lack of research into gun violence, compared with research into diseases like cholera and diphtheria, Kristof had a Times artist compare two data points for each problem: number of people affected and number of research projects funded by the National Institutes of Health over the 40 years ending in 2012.

As you scroll down, try to set aside your political views — whether you’re pro- or anti-gun control — and evaluate this image on how effectively it delivers its message.

graph juxtaposing 4 million gun-violence cases and 3 research grants

I’ve seen very few images that delivered their messages so startlingly, so resoundingly. The numbers are impressive, but the huge red circle and the three tiny boxes thunder out the message: gun violence, while a serious threat to public health, is woefully under-researched. (Kristof says that’s because of lobbying by opponents of gun control.)

Feel free to disagree with the message. But don’t tell me that it wasn’t delivered effectively.

Mapping space and time

Earlier this afternoon, you arrived in an unfamiliar city. Now you want to get out and do some exploring. Where’s an art gallery? A bookstore? A coffee shop?

On a display board at a bus stop, you find a map of the city with points of interest marked. With a little effort you find an interesting-sounding gallery and see that it’s eight blocks west.

The map in front of you describes physical space. Wouldn’t it be nice if the map answered one more question: How long will it take me to get there?

You’re looking to take a trip, not just through space, but through space and time.

You need a time map. Peter Liu, whose company is called Mapbox, is working to design one for you.

As Peter points out, time maps aren’t new. He even found one from Melbourne, Australia, that was used a century ago. But today’s software creates lots of new possibilities.

Melbourne time map

Travel times from central Melbourne via rail, 1910-1922 (source: Peter Liu)

Check out Peter’s time maps for yourself. I especially like the one that changes based on whether you’re walking, riding a bicycle, or driving a car.

Maps are one of my favorite forms of technical communication. Maps have been around for so long, however, that it seems like we already know everything there is to know about making them.

That’s why the time map caught my attention: it’s a new way of looking at something old and familiar.

What do you think? Will we see more time maps in the future? Can they change the way we interact with the world around us?

Informing the public, responsibly

The recent flooding in eastern Texas has engendered a lot of news articles. This one from ProPublica stands out because, in addition to covering a topic of interest, it has all the hallmarks of excellent technical writing.

Let me tell you why.

The lede is up front and to the point

The headline itself conveys the major points: Houston’s Big Dams Won’t Fail. But Many Neighborhoods Will Have to Be Flooded to Save Them. Then, in three brief paragraphs we learn that people are afraid the dams at the Addicks and Barker reservoirs will fail, which would flood much of the city, but despite their fears the dams are safe.

The map is well drawn and emphasizes pertinent data

You can see at a glance the seriousness of the situation. There are the reservoirs, and there are the built-up areas adjacent to them and sometimes inside them. (Yes, inside them. Developers have been allowed to build houses within the boundaries of the reservoirs, on land that — most of the time — is above water level.)

Map showing Houston reservoirs and developed areas around them

Map source: ProPublica

The critical spillways (pink dots) are a bit hard to notice, but they’re called out in the article text.

The spillways, the reservoirs, and Buffalo Bayou, the critical waterway to downtown Houston, are labeled. Less essential details are not.

Background information is explained succinctly

On the assumption that most readers aren’t familiar with Houston’s hydrologic history, the writers provide brief summary information, at pertinent points in the story, about why the two reservoirs were built and how the dams are supposed to work.

Content is organized logically, in short sections

Each section heading is a question, like

  • What are the Addicks and Barker reservoirs? and
  • Why are the spillways a big deal? And what will the impacts of using them be?

The questions build on each other. And unlike with most “frequently asked questions” pages, they’re questions that people actually would ask.

Then each section answers the pertinent question in a few easily digestible paragraphs.

The writing is direct and in the active voice

Picking a paragraph at random:

As of now, the Army Corps says there’s enough excess water in the Addicks Reservoir that some of it is flowing around (not overtopping) one of the auxiliary spillways. The agency originally thought water might also have to flow around the spillways for Barker Reservoir, but now projects that will not be necessary as long as the weather stays good.

The tone is balanced

The article’s tone is businesslike yet reassuring. It reinforces the headline: although this is certainly a big deal, and although people who live near (or in) the reservoirs are going to experience flooding, there’s no cause for general panic.

It’s written collaboratively

Don’t miss the byline. Four different writers are credited for the piece: Kiah Collier of The Texas Tribune, Neena Satija of The Texas Tribune and Reveal, Al Shaw of ProPublica, and Lisa Song of ProPublica. Perhaps one of them, or perhaps an unnamed editor, deserves credit for pulling together everyone’s contributions into a single, coherent piece with consistent tone, vocabulary, and writing style.

I tip my hat to all of them for providing the public with information responsibly and in the proper context.

Postscript: I’m always happy to call out instances of good technical writing that I see in general-interest newspapers and magazines. (Here’s another example, about a different topic.) Do you know of any examples? Please share them in the comments.


Look that up: the lexicographer’s conundrum

Old dictionary advertisement

“The one dictionary that puts your family in command of today’s English”

Some of the best stuff you’ll read on Twitter is the wit and wisdom of Kory Stamper and her fellow lexicographers — including the fresh and very woke tweets from Merriam-Webster itself. Those tweets prove the point that Stamper strives to make in her book, Word by Word: The Secret Life of Dictionaries: that lexicography and lexicographers aren’t as boring as you thought.

Stamper makes her point well, in a distinctively breezy, engaging, and elbow-nudging way. Although a few of her chapters run long, going a little deeper into the weeds than necessary, I recommend the book for anyone who’s interested in writing or language in general.

Old dictionary advertisement

“Accept Nothing Less Than the SUPREME Authority”

The best chapter is the one titled “Marriage,” in which Stamper deftly portrays the tension between lexicographers, who know that their job is to describe the language as it is, and their employers, who for more than a century have touted their dictionaries as the absolute authorities on how our language should be used.

Stamper emphasizes that our language is a river, and lexicographers work tirelessly to discover and track all of its whorls and eddies. It took her weeks, for example, just to update the various definitions of take.

(My use of took in that last sentence is sense 10e of the definition for take, the verb. I haven’t even mentioned take, the noun.)

Yet since the days of Noah Webster, at least, dictionaries have contended in the marketplace by claiming to be authoritative, by insisting that they alone can give you a mastery of words. Funk & Wagnalls, in its pre-Laugh In days, trumpeted that its dictionary contained all human knowledge since the world began.

Old dictionary advertisement

“All human knowledge since the world began is concentrated in this one mighty book”

Even today, Stamper’s own Merriam-Webster displays these words on your browser tab when you display its home page: America’s most trusted online dictionary.

How should we reconcile the difference between the marketer’s insistence on prescribing and the lexicographer’s work of describing — especially in an age when dictionaries rely on online ads, not sales of printed books, to survive financially?

Stamper doesn’t give an answer, and I suppose there probably isn’t one. People expect dictionaries to tell them how to write (and speak), while lexicographers compile dictionaries to reflect what people are writing.

It truly is a question or problem having only a conjectural answer — sense 2a of the definition for conundrum.

Meanwhile, our language flows on, whorling and eddying as it pleases.