First of all, I need to say that this book is not aimed at me. I have been using DITA XML as a technical writer and manager now for over five years, so I am well past needing a “101” lesson in DITA. That said, I think I am qualified to comment on whether a book on DITA is a good and practical guide on the subject. In the end I found this book to be a disappointment. While it does provide a decent overview of what DITA is for a technical writer or manager just beginning to look into the subject, the examples provided are not enough for a beginner to usefully sink their teeth into.
This is a similar complaint to the one I had when I read Managing Enterprise Content: A Unified Content Strategy, co-authored by both Ann Rockley and Steve Manning, as part of my research into devising a content management strategy back in the mid-2000s. I remember finding that book was great on theory, but poor when it came down to dealing with the specifics of implementation. I am finding much the same with this new book on DITA.
What’s Good
This book is designed as a general overview, and to its credit it does that job well. If you are looking to learn what DITA XML is and the basics on how it works and managing a team that is using it, this book is a good place to start. Some of its strongest sections are those that deal with the theoretical background you need to know to get started. So there are brief but solid sections in the book on how structured writing differs from unstructured, the topic-based approach to information inherent in DITA, and how to calculate Return On Investment (exactly what you need to know if you are a manager trying to pitch a DITA CMS to upper management). All solid stuff, and the sort of information that The Rockley Group has done an excellent job of providing over the years.
The section I’d like to single out for special praise is the “Planning for DITA” chapter, which from my experience accurately captures what a manager needs to know when moving an unstructured writing team towards DITA. Overviews of how to do content analysis, the different types of content reuse and why they matter, and the changes to roles you can expect within a team all tally well with my experience. The section that looks at costing metrics is also solid stuff, and seems to be derived from co-author Mark Lewis’ excellent series of articles on the subject.
The Not-So-Good
Where I find the book is weak is in the specifics. For a book aimed squarely at Technical Writers, the examples they choose are poor. Throughout the book they use a set of recipes as the subject for the DITA code examples they use. Everyone understands what recipes are and how they work, so there’s nothing wrong with that per se. It also makes for short and pithy examples, which is also good for a book providing a quick overview on DITA. But I have problems with how the examples get in the way of teaching how to use DITA well.
Almost all of the recipe examples have some form of tabular data in them. No problem there, but the examples they show in code never actually show the table code in full — it just appears as a table would in any spreadsheet. Anyone who has worked with tables in XML knows that there’s a lot more than the <table><tgroup></tgroup></table> tags that are shown in the example code. While I am sure that this is done to simplify things, anyone trying to input the sample code into a working example will fail, and not really understand why.
I think the best example of this type of problem come when they talk about conrefs. When you want to reuse existing text within an existing topic — but not a whole topic — this is where conrefs are handy. Typically, when using conrefs you will be reusing a sentence or two from an existing topic, and possibly even more. The example they provide here is based on the recipes sample. To illustrate how conref-ing works, they have a target file that contains typical units of measure, such as “tablespoon”, “teaspoon”, “cups” and so on. Then from a sample recipe file they conref these targeted terms into it. It works as an example and gets the idea across, but it also suggests a highly inefficient way of using conrefs. Why use a conref tag like conref=”units.php#teaspoon” when you could just type in the shorter “teaspoon” or “tsp.”? My problem with the sort of example is that people may think this is how conrefs ought to be used in practice, which is not the case. A far better example would be to point to some sort of paragraph that is used all of the time, rather than a single word.
One other section I was looking forward to reading was the new section devoted to DITA 1.2. This was far too brief (10 pages!) and lacking in useful example code. It covers the new general task model well, but it only provides a cursory pass on keys and keyrefs, the learning materials specialization, and the constraint mechanism. The final paragraph in this all-too-brief chapter sums up the character of book in many ways: “The specification for DITA is over 1200 pages long and encompasses a number of changes, but many are advanced features not appropriate for an introductory discussion of DITA”. Like what? Could I at least get a hint as to why it is considered “advanced” and why it does not apply? Where should I go for more information? In the end that final paragraph seems like a cop-out for providing more in-depth information, or even basic links on where to find it.
Conclusion
In the end the book provides a decent overview of the subject, and will be good for anyone who is trying to understand what DITA is while not actually trying to put any code-based learning into practice. If you are looking for information on installing and configuring the DITA OT, tinkering with XSL, or decent, well-thought-out and working code examples aimed at Technical Writers, look elsewhere. It’s the sort of book that is good to give to someone who has never worked with any type of structured authoring environment before. It will also be good for anyone who is looking to construct a good R.O.I. argument in order to get a DITA-based CMS. However, anyone with more than a smattering of actual experience in DITA who is looking for something more in-depth should pass on this book.
