About a month ago, we ran an informal survey asking people what publications about DITA would be most useful to them. An author’s guide was at the top of the list. DITA 101: Fundamentals of DITA for Authors and Managers (published through Lulu.com, $25.37 print, $9.95 download), the new book from The Rockley Group, addresses this audience and lives up to its title.
Like every other book about DITA I’ve read, DITA 101 spends a lot of time discussing the DITA philosophy. At first, this troubled me. I’m used to DocBook, where I don’t need a primer on how to write in order to use the schema. My attitude has been, “show me the grammar and leave me alone.”
DITA is different.
Unlike DocBook, which models longstanding practice, but does not “take sides,” DITA grew from a set of design goals that read more like a methodology than an XML schema. One of the real strengths of DITA 101 is that it clearly lays out the design goals and describes, with useful examples, the thinking behind DITA. As a result, in addition to its other virtues, DITA 101 is useful if you are unsure about whether you want to use DITA or not. A careful reading of DITA 101 should give you enough information to know if your current or planned methodology is compatible with DITA.
DITA 101 begins with a short history, which includes a discussion of why you might want to use XML and DITA. This is followed by the aforementioned description of modular documentation philosophy. This section uses recipes to illustrate some of the concepts. For anyone who has seen one of Ann Rockley’s recent presentations, the use of recipes will probably be familiar. I found them to be a useful way of highlighting the idea of topics and maps. They also work well for describing some of the benefits of reuse. Overall, the recipes provided a familiar, but not overly simple, model that helped my understanding.
The next section looks into reuse and tries to answer questions like, why you might want to reuse content, and how DITA can help. It outlines several reasons for reusing content, each of which has a section about Return on Investment (ROI). While I liked the ROI sections, it would have been useful to have a bit more information and references to where the figures came from. The descriptions of various types of reuse (filtered, variable, planned, and opportunistic, to name a few) were also worthwhile.
The next several chapters dive deeper into DITA, starting with a discussion of topics and maps. This is followed by “A day in the life of a DITA author,” which talks about how to plan and develop content using DITA. The next chapter, “Planning for DITA,” could be called “A day in the life of a DITA manager.” It looks at planning, roles and responsibilities, and content conversion, all of which are topics of interest to managers. I particularly liked the description of roles, because it put some meat around the question of “who does what.”
The next section, “Metadata,” is one of my favorites. It begins with an excellent description of what metadata is and why it is important. It then gives a clear description of the various metadata elements in DITA. Not only does it cover the DITA metadata well, it provides a strong argument for using metadata correctly. This is followed by “DITA and technology,” which provides a high-level overview of the kinds of functionality you should be looking for when selecting tools.
The final chapter covers advanced topics, including domains, conrefs, conditional content, relationship tables, and specialization. While this section provided a useful overview, especially the discussion of relationship tables, you will need more information to take full advantage of any of these features. A bit more depth here would have been welcome, though maybe that’s a job for DITA 102.
The book also includes 3 appendices. Appendix A, “Structural visual reference,” is an easy to understand representation of the grammar, or would be if there were a description of the syntax. If you’re familiar with DTDs and schemas, you’ll figure it out, if not, you’ll probably scratch your head a bit before it makes sense. Appendix B, “Prolog Metadata” follows on with a description of the metadata. Both of these appendices, despite my concerns about the visual reference, provide needed nuts and bolts information about the various elements in DITA. Appendix C, “What is XML?,” is a brief overview of XML, along with information about HTML, DTDs and schemas, and XSL. Given the level of the overall text, I might have preferred a more in depth discussion of XML, and less on the other topics, which are of less interest to authors.
The only other minor reservation I have is about the DITA code examples. Instead of being XML, they are screen captures from a tool that I suspect is FrameMaker (it’s been a few years since I used Frame, so I’m not sure). I would have greatly preferred plain old XML. I doubt there’s any danger that readers will mistake the screen captures for actual XML, but if XML isn’t used, it would be good to have a note that describes where the examples came from.
These are minor glitches. Overall, I think DITA 101 is an excellent primer on DITA and I recommend it for authors and managers who want to understand what DITA is all about or need information to evaluate whether DITA is the right solution for them.
