Tag Archives: structured content benefits

Book Review: DITA 101 by Anne Rockley, Steve Manning, and Charles Cooper

Posted on by
2

I’ve benefitted so much this week, from reading DITA 101: Fundamentals of DITA for Authors and Managers (2009), by Ann Rockley, Steve Manning, and Charles Cooper—all of the Rockley Group. Finally, there’s an overview available, which explains DITA at a high-level, as well as describes the benefits of using this XML standard for content reuse. Previously, authors and managers would need to have read the full technical specification to attempt to gather such information.

What is DITA?

DITA 101 explains what DITA is in an easy-to-read and understandable format for the average writer or manager. Is DITA  “a technology? a format? a product? a process?” (p. 1) the book opens, referring to the confusion about the term. By the end of the chapter, we understand that DITA (short for the Darwin Information Typing Architecture) is an open XML standard for structured content:

DITA is an open content standard that defines a common structure for content that promotes the consistent creation, sharing, and reuse of content (p. 7).

A key piece of DITA, the book further explains, is the DITA Open Toolkit— “an open source publishing tool that provides stylesheets for HTML, Help formats, and PDF” (p. 7).

Benefits of Structured Content and DITA

DITA 101 explains the benefits of using this structured approach to writing as speed, consistency, predictability, and reuse (p. 14). Reusing content can also dramatically improve the way content is created in an organization, providing benefits such as reduced development, review and maintenance, reduced translation costs, increased consistency, and rapid reconfiguration of modular content (p. 22).

Building Blocks of DITA: Topics and the DITA Map

Using recipes to explain the structure and models of DITA, the book presents these culinary examples to first illustrate the semantic (meaning) structure of the recipes, and then later on to map the examples to the DITA structure.

In DITA, the major components—the basic building blocks of any output—are  “topics.” The mechanism for putting the topics together is the “DITA map” (p. 31).

Adobe FrameMaker users will recognize the DITA map as similar to the book file, as the DITA map is  “a series of topic references that point to the topics to include in the output when the map is processed” (p. 41).

Separating content from format, DITA provides topic structures for these common types of information:

  • Concept: conceptual (descriptive) information
  • Task: procedural information
  • Reference: look-up-oriented information
    (p.2 and 3).

DITA 101 explains the elements of each information type at a high level, also providing a chapter for more advanced users, with discussions on domains, conrefs, selection attributes (conditional content), relationship tables, and specialization. The appendix provides detailed quick references for DITA topics and for prolog metadata.

Content Strategy

Since, as DITA 101 points out, “the move to DITA often goes hand-in-hand with an organization’s adoption of content management,” (p. 1) the book further integrates strategies for effectively developing and reusing content. In addition to “the architecture (reflected in the models), authors need content development and style guidelines that will help them write content so it is consistent” (p. 15). To this end, the book provides tips on developing style guidelines (p. 17) and on how to write a topic (p. 47).

The Collaborative Authoring Environment

In the chapter on planning for DITA, there is an interesting section on roles and responsibilities, for working with DITA, in a collaborative authoring environment. These jobs include a combination of new and modified positions, compared to the traditional technical writing organization: content coordinator (new), information architect (new), DITA technologist (new), authors (modified role), content owners (modified role), and editors (modified role).

Metadata

The useful chapter on metadata describes an often over-looked topic in technical documentation, which is “very important to an effective unified strategy and is critical when working in a content management system” (p. 61).

DITA and Technology

DITA 101 further provides an especially valuable chapter on  “DITA and Technology,” with a list of key features to look for in an authoring tool (p. 73), and questions to help you decide whether you need a content management system (CCMS), which often goes hand-in-hand with an organization’s move to DITA:

  • Do you have lots of authors (greater than 10)?
  • Are your authors in multiple locations?
  • Do you have a large content suite?
  • Do you translate your content?
    (p. 76).

DITA 101′s clear and practical examples were created using the following editors to capture examples and create content:

XML Alternatives to DITA

In Appendix C, the book continues to do a great job describing XML and structured content at a high-level, in addition to presenting XML alternates to DITA, including DocBook and S1000D.  I especially appreciated the history of DITA, which explained why using DITA can often be preferable to starting an XML implementation from scratch.

The process of creating content models, Document Type Definition (DTDs) or schemas, and stylesheets can be quite time-consuming. Being able to start from an existing markup standard like DITA takes you a giant step along the development timeline (p. 113).

So Why DITA?

According to this appendix, the benefits of implementing DITA, instead of just developing your own SGML|XML markup scheme, or implementing a different XML initiative, are these:

  • Starting from scratch is expensive.
  • DITA is output independent.
  • DITA was designed to support reuse.

Recommendation

I highly recommend DITA 101: Fundamentals of DITA for Authors and Managers to anyone who wants to come up-to-speed quickly on DITA basics. According to the authors, who run a content management consultancy at the Rockely Group, the book covers the major concepts that you will need to understand to implement DITA:

We often get asked how much XML and DITA people need to know. In the early days of DITA everyone, including the authors really had to know XML and DITA, not so now. Today the tools have matured to a point where much of the “guts” of DITA can be hidden from the authors; however, they do need to understand the concepts of DITA at the level presented in this book. Someone who understands the technical details of DITA will be required to be your DITA technologist/systems administrator, but only they need to understand the intricacies of the technology under the surface (p. 55).

Given that the book is only about 135 pages, and some of that includes examples and reference material, most technical writers should feel up to the challenge of mastering the high-level concepts, which this book so clearly presents. Online help writers especially should easily adjust to the topic-based writing approach.

My only small caveats are wishing that the chapters were numbered, in the print version of the book. I also wished that the high-level discussion on XML in Appendix C had come earlier in the book, as I wondered until the very end why one would use DITA instead of an XML implementation from scratch.

Except for these minor suggestions, I found DITA 101 to live up to strong endorsement in the Foreword, as a “valuable contribution to the technical communication literature,” as noted by the Content Wrangler’s Scott Abel.

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog