Tag Archives: DITA

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.

Advertisements

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.

DITA satisfaction: Take the survey

Want to know why people are using DITA? Want more insight into the challenges as well as the benefits?

DITA Survey bannerHere’s a way to get those insights — and do The Content Wrangler a favor in the process. The Content Wrangler, the online persona of Scott Abel, has been for many years a leading voice in the worlds of content marketing and technical communication.

If you’re using DITA, if you’re evaluating it, or if you’re in the process of adopting it, take the 5-minute DITA Satisfaction Survey.

The results, which will be sent to you when the survey is over, will provide helpful data about what people see as the main reasons for using DITA as well as its risks and challenges.

The data will benefit individual DITA users and the DITA community as a whole. It’ll equip us to respond to common problems and complaints, and it’ll inform the DITA Technical Committee about what changes and enhancements are most needed.

Take the survey by May 15 and you’ll be entered into a drawing for Google Cardboard.

DITA adoption: What are the numbers?

I just saw this infographic from IXIASOFT about a subject near and dear to my heart: the adoption of DITA.

Cg_W9ieUoAEuhEC.jpg largeLike so many infographics, unfortunately, this one is a mess. It’s cluttered, with so many elements competing for my attention that I can’t tell what its key messages are.

I don’t expect IXIASOFT to know how to create good infographics. That’s not their business. But I expect them to know about DITA and about the technical writing community in general.

That’s why I’m taken aback by some of their numbers:

  • There are 150,000 technical writers on LinkedIn? Even if that’s a worldwide total, it  seems high. What occupations does IXIASOFT lump under the heading “technical writer”?
  • Only 9,000 say they know DITA? That seems about right – as an absolute number, but not as a percentage of the total. Of the people who are true technical writers, surely more than 6 percent know DITA.
  • 4.0 percent of job ads ask for DITA experience? That’s surprisingly low, considering that by IXIASOFT’s own count more than 600 companies have adopted DITA and a growing number of writers claim to know it. I recall seeing another presentation that put this number in the 10-to-20 percent range, but I can’t place my hands on it. Does anybody have data on this?

I looked on IXIASOFT’s website for illumination. There I found a piece in which Keith Schengili-Roberts put the 6 percent figure into context by noting that only 15 percent of technical writers claim to know FrameMaker. That makes me wonder all the more how broad their “technical writer” umbrella is.

I also discovered that this infographic has been around since at least November 2014. In the earlier version (which you’ll find in Keith’s article) the numbers are slightly different. But they still look suspect.

I’d like to find a truer picture of DITA adoption. Does anybody know of one?

DITA lets the authors drive

This morning, April 1, brings welcome news from the OASIS DITA Technical Committee. Recognizing at long last that DITA authors want and deserve the opportunity to screw up the formatting in their documents, the committee has provided new ways to do just that.

dita-bird-drop“Microsoft Word, the most popular text editing software in the world, lets authors make a royal mess out of their formatting,” explained Technical Committee spokesman Mark Upton. “The users of DITA deserve no less.”

Through XSL transforms, the DITA Open Toolkit has always provided ways to make hash out of document formats. But typically those features fall within the purview of the information architect. Most rank-and-file authors can’t, or won’t, master the necessary XSLT coding skills.

With today’s newly announced features, authors can now create formatting nightmares directly within their DITA topics.

Here’s how it works. Continue reading

Overcoming DITA’s acceptance hurdles

dita-bird_0This is an appeal to the DITA community: the experts and the evangelists, and possibly the tools vendors as well.

We’ve done a good job selling DITA: after years of slow growth it’s gaining momentum. As it does so, paradoxically, I’m hearing more and more anti-DITA rhetoric. While some of the rhetoric reflects a lack of understanding or even a hidden agenda, some is worth listening to.

I’m thinking of two things in particular that the DITA community often touts as selling points: authors no longer have to worry about formatting, and their DITA content can readily be used for adaptive content — output customized for the audience.

As good as those sound, I don’t see content authors raving about them. We need to understand why that is, and find a way to address it.

Leave the formatting to us

I’ve proudly touted this in every DITA class I’ve taught: Freed from having to worry about fonts, indentations, and other formatting issues, authors at long last can concentrate on content.

Except that a lot of authors like to worry about formatting. Continue reading

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

Time to follow a new technology path?

In his keynote talk at the recent TC World conference in Bangalore, Tom Johnson makes the case for creating customer documentation through the use of modern web-development platforms that treat content as code.

Jekyll software logo

Jekyll (software) Logo – source: Wikipedia

Tom invites us, the Technical Communication community, to get past our fascination with XML, which many web developers regard as dated. Instead, he wonders if the time is right to start developing content on popular platforms like Jekyll.

Tom being Tom, he backs his words with action. He’s about to embark on an experiment in which, using Jekyll, he’ll try to replicate the features of DITA. He describes this experiment in the comments section of the same blog post that contains the recording of his keynote talk.

DITA logoI’m an old Tech Comm guy, more a dabbler than a true programmer, so I’m a bit intimidated by the idea of tossing aside my comfortable tool set for something I’ve never used. In fact the phrase “treating content as code” sends a chill down my spine.

Yet I believe Tom is onto something. At a time when we talk about breaking down silos, about leading the effort to unify content throughout the organization, why would we want to wall ourselves off by using our own specialized, peculiar tool set?

I encourage you to listen to Tom’s talk. Then, I’d like to know:

  1. Whether you agree with him — and why.
  2. If you have experience developing documentation using one of the web platforms Tom is talking about. If so, were you successful? What advantages did you find to using the web platform? Disadvantages? Problems you overcame?

I’m sure Tom would like to hear about your experiences too.

I can’t wait to hear about the progress of Tom’s DITA vs. Jekyll experiment. And I hope we can have a fruitful and sustained conversation in our profession about the pros and cons of using web-development platforms — and of using collaborative approaches like GitHub — for creating documentation.

An appeal for DITA keys: Powerful, useful, and mostly ignored

Last week, in his webinar on conditional content, Noz Urbina showed a demo of content reuse using DITA’s conref attribute. I took the opportunity to ask for Noz’s opinion of keys and keyref.

old fashioned keyKeys provide a powerful and useful function, Noz replied. But few people use them because the authoring tools don’t do a very good job of making them easy to use. And the tool manufacturers haven’t added the functionality because they don’t think anybody wants to use it.

It’s the classic chicken and egg scenario.

Noz is one of the smartest people in the content publishing space (and I highly recommend viewing that webinar, if a recording becomes available.) But is the story of keys really as simple as he makes it out to be?

Continue reading

Come down to the river: Structured authoring immersion

You can tell that Mollye Barrett has spent time in the South. During a recent talk on the content lifecycle, the Milwaukee-based content-management expert observed that when it comes to structured authoring, “you need to be immersed. It’s no good just to be sprinkled.”

Amen, sister!

Whether your platform of choice is DITA or something else, structured authoring is different from traditional authoring. Continue reading