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.

Notes:

  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.
Advertisements

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?

Jane Austen ponders technical communication

Last week’s news about the demise of Storify prompted me to go and retrieve a few of my old stories.

One of them, If Jane Austen wrote about technical communication, invited Twitter to complete the sentence

It is a #techcomm truth universally acknowledged, that…

PridePrejudice423x630you cannot safely assume anything about your audience.
– John Kearney @JK1440

it’s never too late. There is always the next iteration 🙂
– Yvonne Wade Sanchez @ywsanchez

buying a tool won’t fix your processes.
– Kai Weber @techwriterkai

when the big boss demands a dumb change, (s)he will later berate you for the dumb thing.
– Karen Mulholland @kemulholland

a person consulting the style guide for an out-of-office reply must be in need of a life.
– Anindita Basu @anindita_basu

the best review comments arrive right after it’s too late to update your content.
– Yours Truly @larry_kunz

you can’t stop people from sticking beans up their nose.
– Kai Weber @techwriterkai

That last one came with a link to Jared Spool’s Beans and Noses — the gist of which is that people will invariably do things that don’t make sense. That’s something we, as technical communicators, have to deal with. And it pretty well sums up life in the year 2017, if you think about it.

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.

The best gifts I’ve received

Gift-wrapped packages

I like gifts. Just don’t say “free gift.” That sets my teeth on edge.

In this gift-giving season, I pause to recognize some of the people who’ve given me gifts during my career. There are lot of them, but these stand out.

The manager who invited me to bring any and every problem to him — as long as I also brought a solution. My solution might not, in the end, be the solution we chose. But it started our conversation, and — most important — it got me focused on fixing, not dwelling on, my problems.

The public-speaking trainer who, early in my career, assured me that my audience wants me to succeed — not make mistakes they can pick apart. To prove his point, he asked me what I want from a speaker when I’m a member of the audience.

A colleague’s advice that speaking or teaching is a form of gift-giving — that my words are something of value, a gift for my audience. People like to receive gifts, he said, and you should enjoy giving them too.

Plastics scene from The Graduate

Just one word: DITA

The team-lead, at IBM in the early 1980s, who encouraged me to learn a precursor of DITA that was just coming into use. Think of Benjamin Braddock and “plastics” — except that I took it to heart. I embraced the idea of structured authoring before I could become too set in my ways as a technical writer. I’ve benefited ever since.

Finally, numerous managers who saw farther than I could and helped me prepare for what was coming — whether it was a new technology or a department-wide layoff. And other managers who took a chance on me, and then — when I didn’t get it right the first time — took a second chance.

I’m grateful to all of them.

I’d like to hear about gifts you’ve received that helped you in your career. Share your stories in the comments.

Letting the team decide

Do you manage by consensus? Do you invite your team to come together to make decisions? Not all decisions, of course, but the many choices that — while not mission-critical – affect the team’s day-to-day work and its esprit de corps.

I admit that managing by consensus isn’t my preferred style. But having worked on teams where members are invited to participate in decision making, I’ve come to see the advantages:

several hands claspedBuy-in: When the team chooses, its members are much more likely to be comfortable with the choice – and with the results of that choice.

Empowerment: Team members feel like their opinions matter, like they’re being heard.

Results: Because it represents the team’s collective wisdom, often the decision is better than anything you would’ve come up with yourself.

Making it work

Before you try managing by consensus, you have to cultivate the right environment to make it work. From my observation, here are some ways to do that.

Assemble a team that’s knowledgeable and trustworthy. You’ll be better able to empower the team when you trust their wisdom and their motivation.

Sometimes – most times, in fact – you won’t get to pick who’s on your team. People are assigned to you, or they come onto your team through reorganizations. What then? You might have to start slowly, until the team (with your encouragement) has established that level of knowledge and trustworthiness – not to mention establishing the ability to trust each other.

Create a framework in which managing by consensus can take place. Obviously, the team can’t make every decision. Decide up front what’s not negotiable, and what kinds of things you’re comfortable letting the team decide. Some of the non-negotiables will be handed down from Corporate. Others will be areas where you have latitude, but about which you feel strongly. Examples might be working hours, or basic rules for professionalism and mutual respect.

Give up your need to be in control. When I’m the person in charge, and I know I’m accountable, this one is hard or me. I can solicit advice, I can ask for feedback – but my buck stops here” mentality makes me want to call the shots. Yet I’ve learned, as I said earlier, that letting the team decide often results in better outcomes than when I decide things myself.

Make sure everyone has a voice. Insist on a culture where one or two people don’t dominate, where everyone feels like they have a chance to contribute. If someone becomes too vocal, or isn’t vocal enough, remind them in a one-on-one conversation that everyone is expected to contribute and everyone has a right to be heard.

Realize that sometimes it’s messy. Life becomes more complicated when you’re no longer calling all the shots. Sometimes, when you ask the team to make a choice, it takes them a while to figure out what they want. There might be strong disagreements along the way, and even healthy disagreement can cause stress. Although you might have to play the role of facilitator, or even referee, resist the temptation to lapse back into the role of boss.

Have you worked successfully on a team where decisions were made by consensus – either as the leader or as a team member? What were the factors that contributed to that success? What benefits came from using the managing-by-consensus approach?

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.

Why do people mangle the language?

confusedAt the recent Australian STC conference, Neil James was asked why people write Manglish, or mangled English. I very much like what he had to say.

(As quoted in Sarah Maddox’s blog, ffeathers. Emphasis mine.)

  • At school, we imbibe the notion that complex writing is better writing. Waffle gets reasonable marks, provided it’s elegant waffle.
  • Early in our careers in the professional and technical workplace, mastering and using the technical jargon of our field gives us a stronger feeling of belonging.
  • When we learn the tech vocabulary of a particular industry, it’s difficult to adjust to communicating with a lay audience.
  • Institutional culture reinforces the language patterns. Large organisations move slowly. It’s hard to change their processes. When you do successfully introduce change, the organisation moves steadily along the new path.
  • Language is used as an expression of power. Sometimes, people deliberately use jargon to protect their financial interests or to manipulate public opinion. An example is from the airline industry, when people use the term “loss of separation” of two planes, which means the two planes collided.

What do you think? Have you experienced a “loss of separation” with some mangled English lately? What might’ve caused it, do you think?

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?

Delighting in our language

Fellow technical writer Tom Johnson has entitled his blog I’d Rather Be Writing.

But lately it seems Tom wouldn’t rather be writing — at least, doing technical writing. In Tom’s words, the day-to-day job of technical writing, especially the plain language aspect, has “removed my ability to delight more in language and to express myself in more articulate, interesting ways.”

Tom describes the essays his wife writes as a student in a Master of Liberal Arts program. She gets to deploy phrases like erstwhile acolyte — phrases that would never find a place in technical writing. For Tom, the thrill is gone. Worse, he says, in both writing and reading he’s lost the delight of learning new words, playing with the language, and “enjoying the eloquence of an author.”

How do I respond to a brother writer in need?

First, by stating the obvious. Erstwhile Acolytes would be a great name for a rock band.

Second, with understanding. Early in my professional life I dreamed of making my living as a “creative” writer. I — and many of my young colleagues — looked at technical writing as a way to put food on the table until we sold that first novel or screenplay. Now, nearly 40 years later, here I am — still working as a technical writer.

But something happened along the way. I came to understand that all writing — including technical writing; maybe especially technical writing — is creative, because problem solving is a creative process. In our case the problem is how to communicate most effectively with the target audience.

Tom mentions the Simplified Technical English (STE) dictionary. Originally developed for the aerospace industry, it stipulates a set of writing rules and a vocabulary of about 900 words. Erstwhile isn’t one of those words, and neither is acolyte. Yet communicating effectively within the constraints of the dictionary is a creative activity. It’s like solving a puzzle.

various kinds of puzzles(Granted, it’s a puzzle in which I reserve the right to change the rules. If I know that the precisely right word happens to be outside the 900-word canon, then dammit I’m going to use that word. Audience trumps guidelines every time.)

So, yes, I don’t get to write erstwhile acolyte in the Installation Manual for E4G Routers. But I get the satisfaction of knowing that I’ve met my audience’s needs. And I’ll shelve erstwhile acolyte until I’m writing for an audience it resonates with.

Which brings me to my last point. Vary your writing by finding different audiences. All technical writing and no play makes Johnny a dull boy. This blog, for example, gives me a platform for reaching a different audience — still professional, but more collegial — than I reach in my day job. Here I can write more expressively and have a little more fun.

So, if you want to recapture the joy of using our language, I’ll suggest to you, as I suggested to Tom, that you try writing for different audiences. Try writing essays or poetry. And each time you write, think of it as solving a puzzle: the puzzle of how to communicate effectively with the audience you’re addressing.

Do you ever find yourself losing your delight in our language? What ways have you found to recapture that delight?