Category Archives: Media and technology

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.

Advertisements

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.

Recapturing community and security

The vast Roebling Mill, near Trenton, New Jersey, produced thousands of miles of steel cable for huge public-works projects like the George Washington and Golden Gate Bridges. At its peak, around World War II, it employed 5,000 people.

Most of those employees lived in a planned community, also called Roebling, in red-brick houses that had been constructed by the Roebling family expressly for their workers to live in.

The loyalty was palpable

When you were part of Roebling, you walked to work beside your neighbors along the leafy streets, through the gate house and down the hill to the factory site. Afterward you walked back together. Perhaps you stopped at the (subsidized) general store or at one of the taverns before going home to your family.

You were part of a community in every sense of the word.

roebling-aerial2.png

The town of Roebling (foreground) and the steel mill in their heyday (Source: Hagley Digital Archives)

Today the mill buildings are gone, although the town with its brick houses and leafy streets remains. The stories of the mill and its people are told in the Roebling Museum, located in the old gate house.

The stories describe a remarkable esprit de corps, a strong bond between co-workers and neighbors who took great pride in their work, whose families gathered together on front porches, whose children competed together on the town’s sports teams.

When you were part of Roebling, the loyalty — yours to the company, and the company’s to you — was palpable.

Nothing lasts forever

When I visited the Roebling Museum earlier this month, those stories reminded me of my first few years at IBM. There I was steeped in a corporate culture that emphasized longevity and two-way loyalty. I never sang songs from the IBM hymn book, but some of my older colleagues had.

On the annual opinion survey, we were asked whether we agreed with a series of statements — one of which was I am confident that, as long as I do a good job, there will be a place for me at IBM. The hoped-for result was that all of us would mark Strongly Agree.

After a while they quietly took that statement out of the survey. After another while, for many of us, the statement proved to be false.

Nothing lasts forever. The Roebling Mill closed for good in 1974 after years of decline. IBM’s first layoffs (sorry, resource actions) took place in 1993. My pink slip came in 2002.

Trying to recapture a little of the old

I’m not suggesting that we can, or even should, return to those days of unswerving loyalty, of living in the safety of the corporate cocoon.

Still, the pendulum seems to have swung too far in the other direction.

Do you work in a place where you feel really connected with your co-workers, with a shared sense of mission and a shared pride in what you do?

Some of you do work in a place like that. But many of you don’t. Perhaps some of you have never experienced what it’s like.

Do you work in a place where you know that your employer has your back, that they care about you as a person and as a professional?

Again, while some of you do, I’ll wager that many more of you don’t.

Community and security

While it’s foolish and naive for workers to believe that the company will always take care of them, there’s value in identifying yourself with a company and in bonding with co-workers.

And while there are no guarantees, there’s also value in knowing that as long as you do a good job, the company will do its best to ensure that it has a place for you.

Community and security. I’ve worked in situations (like those early days at IBM) where I’ve felt like I had a lot of both. I’ve also worked in situations where I had essentially none.

I can tell you which one is better.

So, as managers and leaders, how can we give our workers a healthy, realistic sense of community and security?

Here are a few ideas. I hope you’ll add more ideas in the comments.

  • Let your people know that you value them for the people they are, not just for the work they do. Recognize that some of them might be hurting, having been betrayed by a previous employer they thought they could trust.
  • Invest in your people’s professional development. When you pay for someone to attend a training course, you’re saying that you can see them contributing in the long term, not just on the present project.
  • Let your people have fun together. Even if their families don’t gather on front porches, you can help create an environment where they feel connected by things other than their day-to-day work.

As workers, how can we increase our sense of community and security when there seems to be too little of both? Perhaps that’s a topic for another blog post.

I’d love to hear your story of community and security: how you’ve coped with losing them, or maybe how you’ve lost them and managed to regain them.

Dazzling their giddy readers

Back in 1946 an unnamed editor at the Saturday Evening Post had a bone to pick with the then-current Second Edition of Webster’s New International Dictionary. Specifically, he (given the era and the medium, the editor most likely was a he) was worked up because the dictionary would present all of the various definitions for a word without sufficiently distinguishing the generally accepted ones from the offbeat or archaic ones.

Post cover showing two cleaning ladies in an empty theater

A classic Post cover from, yes, 1946 (source: Saturday Evening Post)

As quoted on Twitter by Peter Sokolowsky, a contemporary lexicographer for Webster’s, the editor had this to say:

Is There a Lexicographer in the House?

This magazine, and every other magazine, we suppose, has frequent recourse to a dictionary for enlightenment on the proper usage of words that crop up in manuscripts. As we are an American publication employing what is called the American language, we use an American dictionary. It is a big, fat, leather-bound volume, heavy enough to snap a man’s instep if it should fall off its stoutly contrived stand. It is also a big, fat fraud. In most instances, it is no more a guide to correct meaning than astrological writings and the prophecies of Nostradamus are guides to the future. Its scholarship, if such pack-rat hoarding of oddities can be called scholarship, is of the on-the-one-hand-and-on-the-other variety. Any meaning, no matter how far-fetched or archaic, can be justified by anyone willing to risk his eyesight on the small print. It doesn’t deserve the title of dictionary, although it is highly ranked in lexicographers’ circles; it is largely an anthology of word meanings and it serves only to compound confusion. The English language, from which our own derives, is an unusually lush language, and our English cousins try in a scholarly way to encourage a reasonably disciplined approach to it. The ungoverned tendency here in America is to admit every novelty with which frontier wits and modern saloon columnists have sought to dazzle their giddy readers.

This seems to be as good a time as any for our lexicographers to get together and work toward some semblance of authority in their works. It is even conceivable that one courageous lexicographer with a sound background and a decent respect for the virility of the American language could cut away some of the spurious trimmings without injuring the tree. Is there such a lexicographer in the house? If not, our language stands in danger of growing so many sucker branches that we won’t be able to see the tree for the suckers.

It’s entertaining to read the rant of a 1946 magazine editor. I’d like to go back in time and ask him what he meant by the virility of the American language.

Whatever he meant, his plea for “a decent respect” for the language gets to the real purpose of dictionaries — especially for those of us who write and edit.

Photo of Webster's Second edition

The “big, fat, leather-bound fraud”: Webster’s Second Edition (source: Amazon)

I think that most writers and editors, and certainly most lexicographers, agree that dictionaries should describe how words are used rather than prescribing how they should be used. Yet merely describing, without making some judgment calls, isn’t helpful.

Why is that? Well, why does a writer consult a dictionary? To ensure that the words we choose will communicate our intended meaning to our readers.

That means we have to know, first, how our readers (our audience, in the parlance of technical writing) will understand the words, based on their backgrounds and their frame of mind. Are they academics? Farmers? Politicians? Are they more or less comfortable with new usage, with slang, with meanings that derive from popular culture?

Then, second, we have to know the words themselves. This is where the dictionary comes in. It should be able to tell me whether the words I have in mind are going to connect with the readers I’m writing for.

If it does, true communication is possible. If it doesn’t, then as a writer I’m simply throwing darts in the dark and hoping they hit something. Or worse, I’m a frontier wit seeking to dazzle my giddy readers.

Please, no. Anything but that.

Epilog: The editor, Sokolowsky notes, eventually got his wish, although he had to wait a while. Webster’s Third, published in 1961, was far more discriminating. In Sokolowsky’s words, it jettisoned the all-but-the-kitchen-sink approach — and that policy has continued to the present day.

Survey says: DITA’s benefits and challenges

DITA SurveyWhat are DITA‘s biggest benefits? Its greatest challenges?

The Content Wrangler is surveying DITA users, and last week Scott Abel — joined by DITA cognoscenti Rob Hanna,Mark Lewis, and Keith Schengili-Roberts — presented some preliminary results.

I’ve listed the rankings here, along with some thoughts of my own. Each numbered item is from Scott’s presentation; the commentary between the numbered items is mine.

(The survey is still accepting responses. If you haven’t yet weighed in, you can do so right now.)

What benefits does DITA provide?

This section was open to all respondents.

1, Consistency: content reuse/single-sourcing
Yes: when I think of single-sourcing, I think of consistency. But I also think about flexibility — of being able to publish the same content on the web, as integrated help, as PDF, and in other formats. For me that’s a big benefit, just as much as — and probably more than — consistency.

2. Usability: structure provides predictability

3. Translation: savings from reusing translation
The panelists remarked that they expected this one to score higher, and theorized that many of the survey respondents were content creators but were not the people actually responsible for translation. I think they’re probably right — and I’d also point out that a lot of organizations simply don’t translate their content. It would be interesting if the survey asked how many are currently translating DITA content.

4. Customization: segmentation, personalization
Nice to see this one crack the top 4. I think we (the community of DITA content producers) are just beginning to take advantage of features like metadata and keys. There’s so much more we can do to adapt content based on the audience’s geographic location, experience level, and so forth. (Key scopes and branch filtering in DITA 1.3 hold out even more promise.)

Rank the biggest challenges associated with using DITA

This section was open to respondents who said they use DITA.

1. Reuse: determining reuse strategy
Conref or keyref? What taxonomy to use, and where to put the metadata (in topics or in maps)? Who “owns” the library of reusable content? There doesn’t seem to be much consensus on best practices when it comes to developing a reuse strategy. Maybe, like the consultants always say, it depends — on what the writing team is
used to, on which groups are collaborating to produce content, and on what the corporate culture will support.

2. Usage: making DITA do what we want it to do

3. Training: equipping staff with skills needed
DITA logoThere’s a ton of training out there — in the basics of structured authoring, in DITA itself, and in the various tools. So I’m not sure what the problem is, unless it’s that companies don’t want to pay for training and want simply to hire people who already know everything (see #7 below). Even if you could hire fully-capable DITA writers off the street (and that’s a big if), they still need to be trained in how to use your local style, transforms, and so forth.

4. Technology: understanding software

5. Formatting: developing stylesheets and rules for content
This isn’t rocket science, but it is serious, hard work. It’s often not considered when companies plan a transition to DITA — which makes it even harder.

6. Governance: enforcing the rules
See number 5 above.

7. Staffing: finding experienced talent

8. Creation: understanding how to create DITA content

9. Measurement: what to measure, how to decide
Let’s be honest: rather than what to measure, don’t we really mean making the business case? We still struggle to quantify the cost savings and revenue enhancement associated with structured authoring and DITA. Translation savings, of course, are a big part of the story. But increased usability, customization, and brand consistency have value too. We just have a hard time quantifying their value.

10. Translation: issues associated with DITA content

So there you have it. What do you think? Do any of the rankings surprise you? Is anything missing from either list?

Do you agree with my take?

Thanks to Scott Abel for conducting the survey. Like so much of what he does, it’s of great value to the technical writing community. Thanks to Rob, Mark, and Keith for their contributions as well.

Improving on perfection

This week brings two anniversaries — one you know and one you probably don’t know. They remind me that every new day brings opportunities for improvement, even when things might already seem perfect.

Sgt. Pepper: Nearly perfect

50 years ago today, the Beatles released Sgt. Pepper’s Lonely Hearts Club Band, one of the best and most influential albums in the history of pop music. Of all the Beatles’ albums I think Sgt. Pepper is the most nearly perfect. Every track is strong. All of the ingredients, from instruments to vocals to harmonies, blend together just right.

Sgt. Pepper album coverYet Giles Martin just completed a project in which he remixed the entire Sgt. Pepper album. In a brilliant interview by NPR’s Bob Boilen, the first question posed to Martin — the son of George Martin, who produced the Beatles’ original albums — was Why? Why would anyone change one of the greatest records ever?

Martin’s answer: in mixing the original album, his father devoted most of his attention to the mono version, not the stereo version — because stereo was relatively new at the time. In the interview, Martin describes how he took the original studio tapes, along with his father’s meticulous notes, and applied a 21st-century understanding of what works and what doesn’t work in stereo sound.

The result, as evidenced by several samples played during the interview, sounds undeniably better than the original. Giles Martin took perfection and improved on it.

My career: From good to better

This week also marks the anniversary of the day I began my first technical writing job. Though far from perfect, my work was pretty good — as evidenced by feedback from my managers and my peers, and by 3 promotions in my first 5 years.

Yet the work I did then pales in comparison to the work I do today. In the intervening years I’ve learned a tremendous amount about audience analysis, about user experience, about writing for my customers rather than my SMEs, and of course about using software and machines to publish content in different media.

My colleague Vincent Reh, describing his career journey from typewriters to modern tools, emphasizes the constant need to learn new skills: “Tools have become so complex and schedules so compressed that most employers can no longer tolerate any kind of a learning curve. Today’s writers are expected to hit the ground running with single-sourcing tools right out of the gate.”

Vincent is right. And it’s not just tools. In my progress from that good beginning to where I am today, I’ve constantly had to learn new skills and unlearn other things. Just to stay competitive.

I fully concur with the words of Alvin Toffler: The illiterate of the twenty-first century will not be those who cannot read and write, but those who cannot learn, unlearn and relearn.

Progress made; progress still to come

It’s nice to observe anniversaries, not least because they remind us of the progress we’ve made. Inspired by the new Sgt. Pepper remix, I’m using this week’s anniversaries to set my sights on progress still to come.

Do you have a professional growth story? How does that story affect the way you view the future? What are you doing to go from good — or from nearly perfect — to something even better?

Making a difference, forever

Be careful what you post on the internet, they say, because once you do it’s out there forever.

I suppose that’s true. In fact, it’s been true since before we had an internet.

In the beginning….

In September 1980, about a year after I hired on at IBM in Kington, New York, a colleague and I started producing a little newsletter to help the technical writing staff master the intricacies of our computer system.

In those days before personal computers, even though we were writing books for datacenter professionals, most of the writers had received only rudimentary training in the practical aspects of using computers to do their work. Our system, the same one the engineers and programmers used, was complicated and not especially user-friendly. (The term user-friendly itself was shiny and new in 1980.)

I think it was my colleague, Susan, who came up with the idea of a newsletter. I eagerly agreed to help. I don’t remember who came up with the name, VM Voice. VM, then as now, stood for Virtual Machine and was the name of that intimidating computer system.

vmvoice

Our maiden issue: Starting with the basics

We started with the basics, gently introducing our readers to VM and its components. Over time we evolved to more complex and specialized topics, always targeting the technical writing staff and its particular needs. Each weekly issue ran to two or three pages — printed and then placed into everyone’s mailbox.

We did about 50 or 60 issues before the well of ideas dried up. Then time passed.

Fast forward to the present….

In March 2017 a longtime IBMer, preparing to retire, was cleaning out his desk. He found a stack of old papers and spotted a familiar name on the top sheet: the same last name as another guy in his office. “Know who this is?” he asked.

“Well, my mother worked at IBM. I’ll ask her.”

Soon the stack of papers was in the mail to Susan, herself long retired. She reached me through a common LinkedIn friend and asked if I remember VM Voice.

Of course I remember. It’s a wondeful memory.

I consider VM Voice to be one of my career’s biggest success stories.

  • We saw a need and we met it.
  • We had fun, especially trying to present complex, even daunting, subject matter in a way that our audience would find comfortable and reassuring.
  • We got instant feedback, and it was almost always positive.
  • We made a difference: the information in VM Voice — homespun as it was — made people better at their jobs.

Seeing those scanned copies of VM Voice reminded me that when you plant a seed, you never know precisely what will happen. When you publish something, either online or in the old-fashioned paper-and-ink way, you never know when and where you might see it again, or who might be affected by it.

The first moral of the story: In technical writing you have lots of chances to make a difference. Never lose sight of that, even when the work seems like drudgery.

The second moral: Before you publish something, make sure it’s good.

Because the internet has a long memory.

And because some people never clean out their desks.

Sassy and also substantial

Peter Sokolowsky

Peter Sokolowsky (Image Source: cbs.com)

We’re having “a national conversation about language.”

So said Peter Sokolowsky, a lexicographer for Merriam-Webster Dictionary, during an interview last week on CBS This Morning.

A national conversation about language? I don’t recall that ever happening before. If you ask me, it couldn’t come at a better time.

When the M-W Dictionary went online in 1996, Sokolowsky explained, it was the first time the dictionary’s curators could see what people were curious about. They’d never before been able to collect data about which words people were looking up.

In the past couple of years we’ve become hyper-aware of fake news, alternative facts, and the ways people use words to twist reality — or accuse others of twisting reality.

The watchers at M-W are doing their part: keeping close tabs on what people are looking up. When United Airlines sought volunteers to give up their seats and then had a passenger dragged off a plane, thousands of people went to the dictionary to look up the meaning of volunteer. Merriam-Webster’s Twitter account took note.Tweet from Merriam-Webster about the word volunteer

Increasingly, M-W’s tweets themselves have drawn attention. Continue reading