Book Review: DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, by Laura Bellamy et al

Reviewed by Richard Mateosian

In the Mar/Apr 2012 Micro Review, I reviewed the IBM Style Guide. This book is a companion to that style guide. It focuses on the Darwin Information Typing Architecture (DITA), an XML-based system for authoring and publishing technical information. Originally an IBM project, DITA is now an open-source toolkit, managed by the independent global consortium Organization for Advancement of Structured Information Standards (OASIS).

DITA provides a technical infrastructure for topic-based writing and publishing. Following a model that evolved from the online-help systems of the 1990s, DITA starts with the idea that most technical documentation can be broken into chunks, and that each chunk falls into one of the following basic categories: procedures, concepts, and reference. The Darwin part of the name comes from DITA’s use of inheritance to allow different projects to extend and specialize the basic categories. Unlike DocBook, another popular XML schema for technical publishing, DITA has an associated set of tools for building an automated process that supports publishing multiple documents to multiple output media from a single database of content.

This book provides a clear treatment of metadata and DITA maps. Metadata — data about the content — provides one key to achieving DITA’s benefits. Properly designing and using metadata makes your content easy for you to manage and for your users to find, and it helps you provide different output to different audiences. While much of the DITA metadata stays with the content, a significant portion of it can reside in DITA maps — structures that define documents in terms of the topics that comprise them and the relationships among those topics. Becoming thoroughly familiar with DITA maps is an important step on the road to feeling comfortable with DITA.

Understanding DITA, especially its architectural aspects, entails digging into the details. DITA is conceptually simple but the details are hard for most people to wrap their minds around. This book helps you understand the details and, by laying out best practices, makes a lot of choices for you, simplifying your task of getting up to speed. The authors are aware of the learning difficulties DITA presents for many users. For example, they begin the chapter on metadata by saying, “If your writing team is just learning about DITA elements, don’t scare them by using fancy words such as metadata at team meetings. Otherwise the guy who brings the donuts might not come anymore.”

If you’re looking for an alternative method for delivering your online Help, or are just interested in pushing the limits with EPUB, this presentation is for you.

Like the IBM Style Guide, this book is sure to become a standard. If you want to work in DITA, you need this book. If you’re not sure you want to work in DITA — it’s overkill for many applications, though new tools and techniques keep lowering the bar — the detailed information in this book will give you a basis for deciding.

DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA by Laura Bellamy et al (IBM Press/Pearson, Upper Saddle River NJ, 2012, 296pp, ISBN 978-0-13-248052-9,, $42.99)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s