A playful blogger walks into a bar

As a public service, and to provide some respite in the midst of a long winter, I’m proud to present this comprehensive collection of “walks into a bar” jokes for professional writers. Feel free to use them without attribution. Please use them without attribution.

A technical writer walks into a bar. He says:

  1. Put an empty glass under the tap marked Heineken.
  2. Pull the lever on the tap.
  3. When the glass is full, push the lever back.
  4. Hand me the glass.
walkintobar

Image source: Tom Mason via Divus Studio London (www.divus.cc)

A minimalist technical writer walks into a bar. She says: Beer.

A web-content writer walks into a bar, and you won’t believe what happens next.

Past, present, and future walk into a bar. The atmosphere grows tense.

A bar is walked into by the passive voice.

A simile and a metaphor walk into a bar, like fog coming in on little cat feet.

The Oxford comma walks out of a bar — leaving behind my parents, Eleanor Roosevelt and Winston Churchill.

Ambiguity walks into a bar. When the bartender sees it, he wipes his glasses.

Redundancy walks into a bar, hops onto a stool, and takes a seat.

A comma splice walks into a bar, it asks for a glass of Bourbon.

A split infinitive tries to surreptitiously walk into a bar, but it gets bounced.

Crowded with happy patrons, a dangling modifier walks into a bar.

After hotly pursuing a hearse, a pun walks into a bar and asks if anyone wants a bier chaser.

Roget paces, steps, and strides into a tavern, pub, or other drinking establishment.

A scholarly writer’s perambulatory movements culminate with his entry into a commercial establishment designed for individual persons to engage in social interaction while consuming distilled spirits.

Knock knock.
Who’s there?
A writer walks into a bar.
A writer walks into a bar, who?
A writer walks into a bar and realizes he’s chosen the wrong presentation format.

Sorry – je ne suis pas circumflex

What’s going on in France?

I’m talking about the way some people are reacting to the modest spelling reforms put forth by the Académie Française. According to a New York Times report, no sooner had the Académie proposed removing the circumflex from some words (only in cases where there would be no ambiguity), than Je suis circumflex became a thing on Twitter. It’s a nod, of course, to last year’s Je suis Charlie [Hebdo] meme.

academie

We don’t need an Academy of English. But if we ever get one I hope it has a classy building like the Académie Française. (Source: Wikimedia Commons)

You might think that I, a lover of language, would join the movement. But I won’t. Here’s why.

I grew up in an orderly home. There were rules. There were right ways and wrong ways to do things. As a result, life was pretty predictable. I liked that.

At school I learned the rules of grammar. I didn’t just learn them — I soaked them up. There was a right way and a wrong way to speak and write. I liked that.

Those rules became ingrained. Never split an infinitive. Never end a sentence with a preposition. Never use a plural pronoun (they) when talking about just one person.

Then a funny thing happened. As I grew older, I watched the English language evolve. I had a ringside seat, in fact, because I made my career in writing.

English evolved, because that’s what languages do. They evolve. Continue reading

Are we driving or being driven?

On my first or second day in my new technical writing job my manager told me, “The CS [customer support] guys have put together a ‘cheat sheet’ for setting up hardware redundancy. They’d just started working with Pat [my predecessor] to get it published as a user guide.”

trends16.png

Image source: Scriptorium

I looked at the cheat sheet: a 40-page Word file describing what works with what (and what doesn’t), the basic setup process, and several “gotchas” to watch out for. Good, useful stuff. Yeah, our customers would like to have this. I can massage it into a user guide.

But when I investigated further, I found a surprise: about half of the cheat sheet consisted of content already in the product documentation. The CS guys were surprised when I pointed that out to them.

So now we have two things going on: the organization has good information that it wants to deliver to its customers. At the same time we’re already delivering good information, but people don’t know it’s there.

My situation exemplifies two of Scriptorium’s Six Trends of 2016 — two trends that at first sound contradictory but actually are closely related in yin-and-yang fashion. Continue reading

Got 20 minutes to help build our profession?

cwsurveybig20 minutes is about what it’ll take to fill out the Content Wrangler’s Industry Benchmarking survey. You probably know the Content Wrangler: he’s Scott Abel, one of the leading voices in technical communication and in the larger community of content creators.

Scott says it’ll take 10 minutes to complete the survey. But I encourage you to ponder over the questions, as I did, and give thoughtful, thorough answers.

Why? Because your answers, along with those of others, will provide a detailed portrait of what content creation looks like today: what tools and techniques we use, what challenges we face, and what we see ahead. It’ll help us understand our profession better and suggest ways to overcome those challenges.

The last such survey, in 2013, gave us just such a portrait. I’ll be interested to see how things have changed over the past 3 years.

Take the survey soon. The survey closes on 15 February, and Scott intends to publish the results around the beginning of March. Everyone who takes the survey will receive a copy of the report. (You’ll also be eligible to win a cool travel bag. But don’t do it for the travel bag. Do it for yourself and for your profession.)

Update 3 Feb: Edited the last paragraph to include the end date for the survey.

We’re in DITA – now what?

Every year my talented friends at Scriptorium roll out a list of trends in content strategy and technical communication. This year’s list is thought-provoking as always: it contains some trends that are spot-on and some that I wasn’t expecting.

And one that’s flat-out brilliant: We’re in DITA – now what?

musclecar

Muscle car (1969 Pontiac GTO – source: Wikimedia Commons, Gtoman)

During the webinar in which Scriptorium unveiled its trends for 2016, Gretyl Kinsey described a “second wave” of DITA adoption: a technical writing team has decided to switch to DITA  — either for the right reasons (as part of a carefully planned strategy) or for the wrong reasons (DITA sounded cool and trendy, or they had some extra money in the budget).

Having gone through the process of converting its content. the team is now finding that DITA isn’t a panacea. The 400-horsepower DITA muscle car is parked in the driveway. Now what do we do with it?

This is when some teams throw up their hands, or when buyer’s remorse sets in. The team, especially if they didn’t have sound reasons for switching to DITA in the first place, might want to return to its old tool set. Or, realizing that they’ve sunk a lot of treasure and talent into the DITA implementation, they’re inclined to limp along — driving the car but never getting out of second gear.

Even when the team made the switch for the right reasons, they might feel overwhelmed. All of the reasons for switching, like cost savings through reuse and greater efficiency in translation, didn’t just magically fall into place. A lot of work is still needed. In this situation, again, some teams content themselves with driving the car to the grocery store and back, never taking it out on the freeway.

What’s the right thing to do? Continue reading

Trying to make things better

Challenger_flight_51-l_crew

The Challenger crew: Michael J. Smith, Dick Scobee, Ronald McNair, Ellison Onizuka, Christa McAuliffe, Gregory Jarvis, Judith Resnik (source: NASA)

Thirty years ago today, with millions watching on live TV, the Space Shuttle Challenger exploded shortly after takeoff. All seven crew members died.

Something else died too, and I’ll get to that in a moment. First, though, let’s remember those seven who “slipped the surly bonds of Earth” and sought to advance humankind’s understanding of space and technology.

Let’s remember also the seven astronauts who died aboard Space Shuttle Columbia in 2003 and the three who died in the Apollo 1 spacecraft in 1967. (In an eerie coincidence, the anniversaries of all three events fall within five days of each other.)

I grew up with the space program in the 1960s. I have an early memory of Alan Shepard becoming the first American to travel into space. (My mother, seated next to me at the TV, said “Pray for him.”) I had chills listening to the Apollo 8 astronauts read from the book of Genesis as they orbited the moon. (I still get chills at the memory.) When Neil Armstrong stepped onto the moon a few months later, it felt like the future was full of possibility.

New_York_World's_Fair

The New York World’s Fair

In the ’60s the world was a mess, just as it is today. But the mood of the time was that science and technology could solve many of our problems. That they could — no, make that would — make things better for everyone. A succession of World’s Fairs, like the one in New York in 1964-65, gave us a glimpse into a future that looked pretty wonderful.

It was an exciting dream. Continue reading

Hey, let’s give it a name

The year’s first big winter storm is expected to hit the U.S. East Coast this weekend. You know it’s big because the Weather Channel has given it a name: Jonas.

twc_screen_shot

Screenshot from a Weather Channel video. I remember the weather being dreadful last February. Now I know who to blame: Octavia, Pandora….

A few years ago TWC started naming winter storms as if they were hurricanes — a  practice that amuses some, confuses many, and edifies practically no one. TWC’s explanation of the “science” behind naming winter storms is a technical-writing tour de force, mixing a few high-sounding facts with colorful graphs and a sprinkling of acronyms, and wrapping it all in a thick coating of earnestness.

Anyhow, I got to thinking. If TWC can give names to winter storms, why can’t we give names to the various parts of the technical writing process? Something like these…. Continue reading

Don’t jeopardize your audience: a lesson in clarity

Did you hear about the Final Jeopardy answer that stumped all of the contestants, causing them to finish the game in a 3-way tie with $0.00? (On Jeopardy, unlike other quiz shows, contestants are given the answers and asked to supply the questions.)

Here’s the answer. Spoiler alert: You’ll find the correct question at the end of this post.

jeopardy19n-2-web.jpg

Source: Sony Pictures Entertainment

Got that? Like a lot of good Jeopardy answers, this one requires you to blend your knowledge of disparate things — mid-20th century history and the locations of presidential libraries.

But unlike good Jeopardy answers, this one is just too convoluted.  It takes a lot of untangling just to figure out what they’re looking for. The name of an event? Umm, no. The name of a president? No again.

They’re looking for the name of a city. See it there, buried in the middle?

Watching all 3 contestants walk away empty-handed should serve as a reminder to every technical communicator: keep it as straightforward as you can. Even (especially) when you’re describing things that are complicated. Use an uncomplicated sentence structure in which the subject and predicate are easy to find and all key ideas receive the proper emphasis.

Otherwise your audience will walk away empty-handed.

The question to the answer: What is Little Rock, Arkansas? Did you know it? (I did.)

What writers need — and don’t need — from SMEs

writer_keys.jpgEver hear a subject-matter expert (SME) complain that they have to do too much of the technical writer’s job for them? I know I have.

I’m afraid that we technical writers have contributed to this attitude, by being lazy and by not helping them help us.

But it’s not all our fault. Sometimes the SME simply doesn’t understand what’s expected of them, and what isn’t.

To help with that, I’ve compiled a list for SMEs of the things your technical writers need from you. (If you’re a technical writer, this list is for you too. Use it to make sure your SMEs are giving you what you need.) Continue reading

Think you’re smarter than your boss?

Awhile back, Amy Gallo wrote in the Harvard Business Review about What to Do If You’re Smarter than Your Boss. I recommend Amy’s article because it’s really about what to do if you think you’re smarter than your boss.

There were two instances in which I thought I was smarter than my boss. Both times, it turned out I was wrong.

Walt: the rustic

Walt (not his real name) was a born-and-bred Southerner, with an easygoing style a and an accent straight out of Mayberry. Still in my twenties, having just moved to North Carolina from “up north,” I quickly pegged him as a rustic.

Walt managed another team at first, but in time I was moved over to his team. I actually thought that while he was nominally the boss, I could pretty much handle things as I saw fit and he’d never be the wiser. (I was a cocky young pup, wasn’t I?)

Once I began working for Walt, and I was able to see him close-up, things changed. Continue reading