Category Archives: Media and technology

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

Review: The Dance of the Possible

(Subtitle: The mostly honest completely irreverent guide to creativity)

dance_of_possibleScott Berkun has delighted me in the past with books like The Year without Pants and The Ghost of My Father. Engaging and original, they touched me in such a way that, long after I put them down, their insights remain fresh in my mind.

Yet after reading the first couple of chapters of The Dance of the Possible, I thought Berkun had let me down. In this, his “guide to creativity,” he was telling me that creativity comes from inside me. That I should keep a journal. The messages seemed shopworn, not original.

Then he hit his stride. Or maybe I just opened myself to listen to him. At any rate, the rest of the book proved to be entertaining, practical, challenging, and authentic.

Authenticity was the secret ingredient in Berkun’s earlier books. He’d embark on a journey of discovery, often self-discovery, and invite me to walk alongside.

This time he’s already gone ahead. He’s done the research and he’s created things. (This is his seventh book.) In The Dance of the Possible he’s left me a set of detailed signposts – showing me how to find my creative path and what to expect along the way.

There’s plain-spoken guidance on topics like finding and nurturing ideas, developing discipline, and seeking feedback.

You can read this book in an hour or two. But don’t. Linger over it. Underline. Jot down notes. (Start that journal.) And, when you’re finished, keep the book handy so you can refer back to it.

Or read a chapter at a time. Most of the chapters are little essays, two or three pages long, about some aspect of the creative process. Each one can stand by itself while complementing the others.

Dancing, it turns out, is an apt metaphor for the creative process. I won’t spoil the book for you. I’ll just say that dancing requires intention, it’s something you can learn to be good at, and – above all – it’s fun.

Four stars out of five. Maybe four and a half.

An abridged version of this review was posted on Goodreads and amazon.com.

Create your story — and choose the right ingredients

Seth Godin took me to school. Oh, I’m sure he doesn’t realize it. But his April 11 blog post sounded like a direct rejoinder to my earlier piece: Just the right choice of words.

Here’s what Seth had to say:

If you watch a well-directed film with the sound turned off, you’ll get a lot out of it….

There are a few places where all that matters is the words. Where the force of logic is sufficient to change the moment.

The rest of the time, which is almost all the time, the real issues are trust, status, culture, pheromones, peer pressure, urgency and the energy in the room.

In fact, Seth’s post echoes the response Mark Baker wrote to my piece:

It isn’t the choice of individual words. It is the juxtaposition of words that achieves the effect. The art is not in the selection but in the arrangement, not in the vocabulary but in the story.

Both Seth and Mark know their stuff. So, did they take me to school? Do I feel chastised? Ready to write a retraction?

Um, well….No. Continue reading

The first all-emoji technical manual

This week the technical communication world is abuzz over the April 1 release of Remco Children’s Bedroom Suite: Assembly Instructions. Written by breakout author Julian Rebusser, it’s the first technical manual written entirely in emojis.

Recently I caught up with Rebusser, Skyping from a very hip coffee shop on the West Coast, for this exclusive interview.

Leading Technical Communication: Welcome, Mr. Rebusser, and thank you for agreeing to appear in my blog.

Rebusser: You’re welcome. I read somewhere online that your blog is influential, and I’m all about building my personal brand.

Tell me about your new book.

It’s got all the instructions for unpacking and assembling a full suite of children’s furniture: bed, night stand, armoire, desk, chair. For a few extra bucks you can even get a lamp

Assembling all of that must require a lot of complicated steps.

Yes. And when I wrote it as a conventional manual, it was like 20 pages of crap

What inspired you to write an all-emoji technical manual?

I had an epiphany one morning, waiting for the barista to brew my double-shot caramel macchiato

Wow. What was that like?

Well, for the first time ever, I thought about my audience.

You hadn’t thought about your audience before?

Of course not. Great writers don’t think about their audience. They think about cool, hip ways to express themselves. But for 2 or 3 minutes that morning, for some reason, I thought about my audience. And I realized something.

What did you realize?

Well, who usually assembles a furniture set for children?

Their parents, I suppose.

Right. And who are those parents?

I’m not sure I follow.

They’re Millennials! Digital natives. People who don’t read books

They don’t read books?

Of course not. They don’t like to read anything. I saw that in an article online.

And so the children’s parents….

Right. If I gave them words they’d never read them.

So, instead, you gave them….

Emojis! Millennials love emojis. I saw that online too. And I knew I was perfect for the job because I speak fluent emoji.

What happened next?

In no time my 20-page draft was down to 2.

Can you give me an example?

It used to take a whole page to explain how to bolt the legs to the bed.

And now?

Now it’s boltlegslegstwobed

I — I’m speechless.

I presented this last week at Write the Docs, and they were speechless too.

So now everyone knows you as the first all-emoji technical writer. What’s next?

Well, it’s all still hush-hush. Can you promise to keep a secret ?

Sure.

Next year when Remco rolls out its do-it-yourself flower garden, I’ll be there with an emoji-based augmented-reality experience. I’m calling it Pokemon Grow.

I can hardly wait.

It’ll totally blow your mind.

Yeah, I’m sure it w– mind blown

Opening the door to singular they

Have you heard? The Associated Press Stylebook is “opening the door” to singular they. The new entry reads:

They, them, their In most cases, a plural pronoun should agree in number with the antecedent: The children love the books their uncle gave them.They/them/their is acceptable in limited cases as a singular and-or gender-neutral pronoun, when alternative wording is overly awkward or clumsy. However, rewording usually is possible and always is preferable. Clarity is a top priority; gender-neutral use of a singular they is unfamiliar to many readers. We do not use other gender-neutral pronouns such as xe or ze.

(quoted by Gerri Berendzen on the American Copy Editors Society website)

You might be thinking Why are people still talking about this? Hasn’t singular they established itself in the language?

I’d say that it has. I salute AP’ for recognizing that. Even so, they give the appearance of being dragged into it, kicking and screaming and holding their collective nose. Continue reading

Is “soup to nuts” what we need?

For almost as long as I can remember, pitchmen (especially on late-night TV) have been selling all-in-one gadgets that slice, dice, puree, and do pretty much everything.

In our world of technical communication we have something similar: “soup to nuts” authoring systems that combine all the major steps of the content workflow under one banner:

  • Creating content
  • Managing content
  • Reviewing
  • Publishing
breakfast_gadget

This is actually a thing — but are you using it in your kitchen? (Source: Nostalgic Electrics)

Vendors have been offering systems like this for several years. The sales pitch is alluring: unify all of your content under the banner of one integrated toolset. Lots of content, a multi-step workflow, and one brand to rule them all.

Yet I don’t think I’ve ever seen a company, or even a decent-sized organization within a company, use one of these single-vendor systems for its entire content workflow.

I’ve used parts of these systems. For example, I’ve used easyDITA for content management and publishing, but not for content creation and reviewing. I’ve used XMetaL, but only for creating and publishing content.

In fact I’ve never used these systems for reviewing. All of my SMEs have said the same thing: “Give me a Word document or a PDF that I can mark up. Don’t make me learn a new tool.”

Do any of you use a single, soup-to-nuts system to create, manage, review, and publish content? If so, I’d like to hear from you. Is it working well for you? How easy was it to set up, get buy-in from content producers and SMEs, and train everyone? Continue reading

Is augmented reality part of technical communication’s future?

While walking my dog last night I came upon a mother and her young son standing on the sidewalk. She was holding her smartphone high in front of her, pointing it toward the western sky.

As I came near she announced, “Mars and Venus.”

skymap_screenshots

The Sky Map map (Screen shots from Google Play)

I learned the names of the planets and stars the old-fashioned way: standing outside on cold nights with my dad, and studying the sky atlas he gave me. But today I guess there’s an app for that. There are actually several apps, as a cursory Google search will attest.

I think it’s cool that you can aim your phone at the sky and learn the basics of stargazing. I think it’s very cool that many of the apps are using augmented reality.

When I got home I downloaded one such app, Sky Map. True to its name, Sky Map immediately gave me a clear, easy to use map of the heavens. I haven’t yet sussed out what all of the icons mean. But I had fun using the Time Travel feature to see the positions of the moon and planets on the day I was born.

Do I sound like a space geek? Guilty as charged.

When it comes to augmented-reality apps, though, I’m still unsure about a couple of things.

No business case?

Number one: the stargazing apps are very low-cost. Many, like Sky Map, are free. So it’s hard to see whether there’s a business case for using AR in training and technical communication.

I write documentation for networking hardware — switches and routers. I can easily imagine how customers would like AR documentation that shows them how to attach brackets to switches and mount them together in a rack. But does customers would like translate to customers would pay for? Or to customers would choose my company over our competitor?

In the absence of clear answers, would my company invest in the tools, time, and training needed to develop such documentation?

Not ready for prime time?

Number two (and maybe this follows from number one): it seems so far that AR is mostly the province of gamers and app developers — not technical communicators or training developers.

skymap_screenshot2

Time Travel, Sky Map style. Recognize the date?

Most of the literature about AR in technical communication is still speculative. An article might say, for example, Here’s what AR is, and here’s how I think it could be applied to tech comm. Or: Everyone loves AR, and tech comm is on the verge of embracing it. I’ve seen only a handful of isolated case studies in which AR actually is being used for technical communication.

One such case study is General Motors’ myOpel app. GM began distributing the app to Opel owners a few years ago. Does anyone know if they’re still doing so? Or if they’ve expanded the idea to other brands? (A quick peek at Google Play reveals that myOpel is still available but it’s getting only tepid reviews.)

So, despite the star-struck articles (one of which — full disclosure — I wrote in 2013), I remain unconvinced.

What do you think? Do the stars say that AR will be a big part of technical communication’s future? Have you done AR work for technical communication or for training and if so, have you succeeded in making the business case for it?