Story and data: yin and yang

I saw a story without any data. It was like a milkshake without any flavor.

First, some background: Mark Baker recently wrote a piece in which he rightly derided the DIKW (data, information, knowledge, wisdom) pyramid as a model for communication. He pointed out that pure data, without a story to give it context, is meaningless.

Sea turtleThen he set out to replace the pyramid with a different model: a stack of turtles, each one riding on the back of the one below it. The stack, in Mark’s words, “is stories at the bottom, in the middle, and at the top. It is stories, like turtles, all the way down.”

That sounded good to me. Then I saw a story without any data. Continue reading

Review: “Learn Technical Writing” online course from Udemy

Screen shot titled

A screen shot from the introductory part of the course

Udemy recently invited me to try their online course, Learn Technical Writing & Make an Average of $67,910 a Year. As the name suggests, the course is aimed at those who are new to technical writing or who are considering making technical writing their career.

Well-known technical author Dr Ugur Akinci developed the course and provides the audio narration. While I often wished that he wasn’t simply reading the slides, I very much liked his tone: warm, confident, supportive. Continue reading

Pluto and the art of patience

Last week, after a nine-year journey, NASA’s New Horizons spacecraft reached its destination and started sending back images and other data about Pluto and its moons. In their news conferences, the NASA scientists are practically giddy with excitement — as well they should be. The images have been breathtaking.

Pluto as seen by New Horizons

Until very recently we knew this only as a spot of light (source: NASA)

These images are just the first taste of what’s to come, however.

Aimed at earth from 5 billion kilometers away, the signal from New Horizons is understandably weak. The bandwidth for the downlink is so limited (1,000 to 4,000 bits per second – much slower than a 1990s dial-up modem) that it’ll take until the end of 2015 just to get the compressed data. It might take until late 2016 to get all of the data in full resolution.

In other words, we’ll have to be patient. Those of us above a certain age can remember taking pictures on vacation and then waiting several days for the drugstore to develop them. It’s going to be like that with New Horizons.

After all the data arrives, it’ll take a while longer for the scientists to interpret it and develop realistic theories about what’s going on with Pluto and the moons: their composition, geological activity, and so forth.

Until then, we wait. In spite of their excitement, the scientists are cautioning everybody not to jump to conclusions, even though they — as much as anyone — surely understand the temptation to do just that.

As a technical writer I know about the temptation to jump to conclusions.
Continue reading

Lowering the bar

I recently saw a job posting in which the first line under “Responsibilities” went like this:

….deliver [content] that engages audiences, and that is virtually free of spelling, grammar, and formatting mistakes

Misspelled road sign: shcool

S-h-cool? Hey, don’t worry. It’s cool.

Got that? The first requirement of the job – the number one expectation — is that my content will contain spelling, grammar, and formatting mistakes. Not a lot of them, mind you. But the word virtually ensures that there’ll be a few mistakes.

Look, I know we’re all human and we all make mistakes. But they set the bar way too low when they say that I — or the successful candidate, since I won’t be applying for this job — will be expected to make mistakes.

Even without the word virtually, I’m afraid that “free of spelling, grammar, and formatting mistakes” is still a very low bar. There’s nothing about making my content accurate, useful, and relevant to my reader. “Free of mistakes” diminishes who I am as a professional. It trivializes my work as a technical communicator.

I imagine this employer would have little use for the idea that technical communicators contribute bottom-line value to the business. Or for the idea that their customers deserve high-quality information. After all, a few mistakes aren’t going to matter.

What do you think? Am I overreacting? Or am I right to be offended by the attitudes that this job posting implies?

Our #techcomm mission statement

Here’s our new mission statement.

Few sentences are more likely to send a professional community into full-on rewrite mode, sharpening their red pencils, adding a nip here and a tuck there. All the more so when the members of the community are technical writers.

Sarah Maddox just proposed a mission statement for technical writers, and it’s a good one:

Make complex goals achievable within our customer’s context

Quill penIt’s good because it’s direct and it provides a vision of what we’re all about. It’s good because the word customer reminds us that we’re engaged in a business and the customer (paying or prospective) is paramount. It’s good because there’s no bafflegab like charging paradigms or maximizing synergies.

Still… Here comes my red pencil. Continue reading

The arc of history bends a little more

Like the obedient son in Matthew 21, the South Carolina House of Representatives hemmed and hawed and stamped its feet, and then it did the right thing. Like the obedient son, the 94 House members who voted to take down the Confederate battle flag ought to be given credit for that.

Confederate battle flag at South Carolina Capitol

It’s coming down. Hallelujah!

Not everyone will agree.

To those who say the Confederate battle flag symbolizes something noble, that it doesn’t stand for bigotry and hate: Symbols matter.

As every technical writer knows, we never use symbols that would be offensive in any culture where our content might be used. So, even though the thumb and forefinger forming a circle means “OK” in the U.S., we’d never include a picture of that gesture because to much of the world it’s insulting or vulgar.

To those who say the flag honors the bravery of forebears who fought in the Civil War: I’d be more inclined to believe you if you said the same thing about forebears who fought in the Vietnam War.

In the 1960s, just as in the 1860s, hundreds of thousands of young men were told that the war was just and that fighting was the honorable thing to do. They went and they fought bravely. Tens of thousands never came home. So why don’t we hang a South Vietnamese flag next to the Confederate flag?

Martin Luther King famously said “The arc of the moral universe is long, but it bends towards justice.” If the South Carolina House vote causes a few people to look honestly at this symbol and think about why they’ve embraced it for so long, then the arc will have bent a little more.

Image source: Charleston Post and Courier

Technical Communication A to Z

Last week Stan Carey, editor and blogger, gave us his A-to-Z of linguistics.

In the spirit of paying homage to Stan’s marvelous work, or maybe just in the spirit of crass plagiarism, I now present Technical Communication A to Z.

A is for agile, with scrums and with sprints;
B is for books, if you like yours in print.

dita-bird_0C is for content, which some say is king;
D is for DITA, it’s still evolving.

E is for editors, some gentle, some crusty;
F is for FrameMaker, solid and trusty.

G is for Google, our path to Page One;
H is for help systems, show how it’s done.

Jekyll software logo

I’d rather be writing is what I is for;
J is for Jekyll, which techies adore.

K is for KPIs, things that we measure;
L is for L10N, always a pleasure.

M is for Madcap, performing with Flare;
N is for new tech, devices you wear.

KeyboardO is for oXygen, and writing’s a breeze;
P is for PDF, ’cause we’re still killing trees.

Q is for QWERTY, for typing with speed;
R is for rewrites, from regal SMEs.

S is for STC, a group we all love;
T is for Tekom, same as above.

STC logoU is for users, who make it worthwhile;
V is for value, which always trumps style.

W is for Word, ubiquitous tool;
X is for XMetaL, shiny and cool.

Y is for yellow, as in Post-It notes,
Z is for zip files, and that’s all he wrote.

Extroverts and introverts: We’re all relevant

Can't we all just get along?On June 15 Bobby Umar devoted his weekly Twitter conversation, #PoCchat (Power of Connection), to the question of how introverts can become “relevant to connection and leadership.”

I like #PoCchat a lot. Bobby picks great topics, and his thoughtful questions always spark good discussions. But I was taken aback by the thrust of his questions, as well as by some of the answers. Do people still think that introverts aren’t relevant?

Business writers have been devoting a lot of attention to the 30 to 40 percent of people who consider themselves introverts. Notably, Susan Cain’s Quiet Revolution — first a book, then a website, next (who knows?) maybe a major motion picture — uses personal stories to rebut the idea that introverts can’t succeed as leaders and as high-profile performers.

All of which prompted a somewhat, but not entirely, tongue-in-cheek rejoinder from leadership coach Jesse Lyn Stoner: Confessions of a Closet Extrovert: We Need a Champion, Too.

Yet with all the attention being paid to extroverts, introverts, and their roles in modern businesses, a few myths still need to be dispelled: Continue reading

ContentHug: Technical communication’s present and future

ContentHug logoVinish Garg recently interviewed me for his ContentHug website. We talked about the evolution of technical communication, the role technical communicators can have in disruption, and what I’d wish if I could wave a magic wand.

Check it out — and leave a comment to tell me what you think.

Closing the #techcomm technology gap

The Library of Congress houses more knowledge than any other institution in the world. But is knowledge really knowledge if nobody can read it?

Library of Congress, circa 1890

The Library of Congress, circa 1890. Apparently, even then it had trouble cataloging all of its content.

This week James Billington, the Librarian of Congress since 1987, announced that he plans to retire on January 1.

The story behind Billington’s resignation, as often happens when someone is on the job for so long, is complicated. In recent years Billington has come under fire from critics for several aspects of his leadership. The biggest complaint, however, is this: the Library suffers from a serious technology gap.

According to the news report about Billington’s resignation, “just a small fraction of [the Library’s] 24 million books are available to read online.” The article also hints at a cataloging problem: millions of printed pieces – some dating to the 1980s – are piled in warehouses, waiting to be shelved. It’s a problem that might be alleviated with the right application of technology.

Billington and his defenders argue that he’s started the Library on the path toward modernization. Of course he has: he’s been on the job since 1987. So even if the Library is using 1990s technology he can take credit for it. But when all’s said and done, it’s clear that the Library is late to the technology game.

Like the Library of Congress, we technical communicators are in the business of making knowledge available to people who need it. Continue reading