Learn about DITA in a couple of hours

DITA 101, second edition, by Ann Rockley and others is one of the best tool-independent books about DITA. It’s a good primer to learn about DITA in a couple of hours.

Strong context

The book excels in firmly embedding DITA’s technologies and workflows in the larger contect of structured writing and topic-based authoring.

I attribute this to the authors’ years of solid experience in these areas which comes through, especially in the earlier chapters.

“The value of structure in content,” the second chapter, illustrates structured writing with the obvious example of cooking recipes. Then it goes on to show you how to deduce a common structure from three realistically different recipes – which I hadn’t seen done in such a clear and concise way.

“Reuse: Today’s best practice,” the third chapter, takes a high-level perspective. First it acknowledges organizational habits and beliefs that often prevent reuse. Then it presents good business reasons and ROI measures that show why reuse makes sense.

Comprehensive, solid coverage

From the fourth chapter on, Rockley and her co-authors describe DITA and its elements very well from various angles:

• “Topics and maps – the basic building blocks of DITA” expands on the DITA specification with clear comments and helpful examples.
• “A day in the life of a DITA author” is very valuable for writers who are part of a DITA project. Writing DITA topics and maps is fundamentally different from writing manuals, and this chapter highlights the essential changes in the authoring workflow.
• “Planning for DITA” outlines the elements and roles in a DITA implementation project for the project manager. Don’t let the rather brief discussion fool you: Without analyzing content and reuse opportunities, without a content strategy and without covering all the project roles, you expose your DITA project to unnecessary risk.
• “Calculating ROI for your DITA project” has been added for the second edition. It’s by co-author Mark Lewis, based on his earlier white papers: “DITA Metrics: Cost Metrics” and “DITA Metrics: Similarities and Savings for Conrefs and Translation“. It expands on the ROI discussion of chapter 3 and creates minor inconsistencies that weren’t eliminated in the editing process.
• “Metadata” first introduces the topic and its benefits in general and at length. Then it describes the types and usefulness of metadata in DITA. This might seem a little pedestrian, but it’s actually helpful for more conventional writers and for managers. It ensures they fully understand this part of DITA which drives much of its efficiencies and workflows.
• “DITA and technology” explains elements and features to consider when you select a DITA tool, content management system or publishing system. This always tricky to do in a book as much depends on your processes, organization and budget. While the chapter cannot substitute for good consulting, it manages to point out what you get yourself into and what to look out for.
• “The advanced stuff” and “What’s new in DITA 1.2” continue the helpful elucidation of the DITA specification with comments and examples that was begun in the “Topics and maps” chapter.

Mediocre organization

For all its useful contents, the book deserves better, clearer organization!

• Redundancies and minor inconsistencies occur as concepts are defined and discussed in several places. For example, topics are defined on pages 4, 24 and 46. The newly added ROI chapter complements the ROI points in the third chapter, but neither has cross-references to the other.
• The index doesn’t always help you to connect all the occurrences and navigate the text.
• Chapters are not numbered, yet numbering of figures in each chapter starts at 1. It’s not a big problem, because references to figures always refer to the “nearest” number, it’s just irritating.

Formal errors

The book contains several errors which add to the impression of poor production values. They don’t hurt the overall message or comprehensibility, but they are annyoing anyway:

• Mixed up illustrations such as the properties box in Word (page 72) vs. the properties box from the File Manager (73)
• Spelling errors such as “somtimes” (1) and “execeptions” (16)
• Problems with articles such as “a author” (20) and or a system that “has ability to read this metadata” (77)
• Common language mistakes such “its” instead of “it’s” (52)

Lack of competition

Another reason why it’s still one of the best books on the topic is that there simply aren’t many others!

• Practical DITA by Julio Vazquez is the only serious contender, and its practical, in-the-trenches advice complements Rockley’s book very well.
• [More books are pointed out in the comments, thanks everybody! – Added January 11, 2010.]
• DITA Open Toolkit by “editors” Lambert M. Surhone, Mariam T. Tennoe, Susan F. Henssonow is a compilation of Wikipedia articles. Amazon reviewers call other titles produced by the same editing team and publisher a scam.

Of course, several other honorable and worthwhile books include articles or chapters on DITA and/or discuss DITA in context of specific tools.

My recommendation

Despite its shortcomings, the book’s own claim is valid: “If you’re in the process of implementing DITA, expect to do so in the future, or just want to learn more about it without having to wade through technical specifications, this is the book for you.”

I recommend that you read it if you are

• Involved in a project to implement DITA
• Writing or translating documentation in a DITA environment
• Managing technical writers

Your turn

Have you read this book? What’s your opinion? Can you recommend other books or resources about DITA? Feel free to leave a comment!

Advertisement

Top strategies to embrace cost metrics

Moving to a structured writing environment can change the metrics of documentation. That’s one of the lessons I learned in a great webinar by Scriptorium‘s Sarah O’Keefe about  “Managing in an XML environment”.

If you’ve missed it, check out the 45-minute recording/slideshow on their website. You’ll find it very interesting, if you’re wondering what it will be like to create and maintain documentation, once you have implemented XML. I’ll summarize a few aspects that I found interesting and comment on them.

XML increases transparency

Creating documentation in an XML environment increases the transparency in writing documentation, for better or worse. Tech writers’ work in XML is more visible earlier in the process: Without XML, a writer may deliver a print-ready PDF after months. With XML, she might check in topics every day for a nightly build.

Just as content gets chunked from books to topics, so progress gets chunked from weeks and months to hours and days. What can be measured often will get measured, so Sarah warns: Beware of seductive metrics. Measuring pages per day, for example, is silly: It will increase page count, but not necessarily the quality or the effectiveness of the documentation.

Strategy #1: Learn to QUACK

Measure something useful instead. Sarah suggests the QUACK quotient:

(quality + usability + accuracy + completeness + “konciseness”) / cost

Sarah goes on to define each of the five “QUACK” factors in similar terms as Gretchen Hargis, et al. in Developing Quality Technical Information. For example, quality considers whether the documentation is well-written and well-structured. “Konciseness” (spelling follows acronym as form follows function) means to provide as little documentation as is necessary, but no less. This improves efficiency for users and localizers alike.

I think this approach is great for scenarios where you can’t get out of cost metrics. Using accepted quality criteria is definitely better than being held to junky metrics.

But I wonder how quantifiable the five dividends actually are: How accurate is a topic? “Very accurate”, if I’m lucky – but I wouldn’t know how to put a number on that… Also, each dividend should be weighted according to audience and industry, Sarah explains. For example, completeness of documentation is more important in regulated industries than video games. That doesn’t make the quantification any easier or less contested.

Strategy #2: Duck the cost

My own strategy requires even more leverage for tech writers than just pushing a new formula through to assess our work. So it probably doesn’t work for all tech writers.

The QUACK quotient takes for granted that documentation is a cost center. Of course, many managers share that view. But I wonder if we tech writers wouldn’t be better off, if we got out of that defensive corner altogether.

I think it helps us more in the long run to show how documentation contributes to the larger corporate processes of production and value added. So I suggest that it’s worth to argue along these lines:

• Turn transparency into cost attribution: Show how each topic’s cost can be counted towards the development cost of the feature or part that it describes, just like other stages in the production processes. It’s like applying total cost of ownership to your own products.
• Turn topic reuse into corporate efficiency and assets: Show how reused topics create extra value or reduce costs in other departments, for example, in training, customer services or marketing.
• Measure relative cost savings: Show how writing XML-based documentation is more efficient than the previous non-XML process, once you’ve overcome the initial hurdles.

Bonus link: Cost metrics white paper

If you’re into DITA or want to see how cost metrics for structured writing break down to actual numbers, check out Mark Lewis’ clear and thorough white paper “DITA Metrics: Cost Metrics“:

You’ve already concluded that moving to DITA will save you tons of time and money. But management says prove it. This paper helps you determine the cost portion of the ROI calculation. What are my costs now? What will my new costs be with DITA? And what is the difference—my savings?

Your turn

What do you think is the best way to justify tech writing cost? What scenarios or strategies have you seen succeed or fail? Share your thoughts in the comments.

DocTrain West 2009: Mark Lewis on “DITA Metrics: Cost Metrics”

Mark Lewis‘s session presented metrics with which you can show ROI for DITA by reusing identical and similar topics. See Lewis’ White Paper here on the Content Wrangler for details.

An engaged discussion ensued which shows the interest in tangible metrics:

• There was no immediate answer about the total cost of ownership for converting to and maintaining DITA. But the burden of proof in terms of TCO shouldn’t rest with the documentation team – which most likely doesn’t have all the numbers for it, anyway. Instead, the team can try to figure what management is willing to spend money for and try to tap into that.
• If you have a diverse team where some writers are faster than others, you can either use a mean topic development time (instead of the average; see the comment wall of the DITA Metrics group in the Content Wrangler ning network). Or you can use normalized sizes and assign each writer a factor to define how long he needs to complete one of those development sizes.