Author: Eliot Kimber, XML Press
I will start this review with my conclusion:
I recommend this book for the DITA developer, and also for the person designing your DITA Information Model. Some parts are useful for the writer who is using DITA, but there are other books for them.
In this review, I will describe how I think the software developer for a DITA implementation, someone whom Kimber would call a DITA Practitioner, should use this book for the first year or more of their first DITA deployment. Then I will describe what parts of the book I think an Information Model designer should concentrate on.
For the DITA developer:
When I got Eliot’s book in April 2012, I thought I had a good grounding in DITA development.
However, I found in “DITA for Practitioners” a lot of useful data that I had not seen before. In some areas, I thought the writing was a bit pedantic, but I often found that valuable nuggets of information are hidden inside even those parts.
First, Chapter 1 is a good summary about DITA. I refer new DITA developers to it. It helps define what you need to know when you move to DITA from other technologies. It explains that DITA looks very differently at XML processing compared to previous systems. DITA especially treats all processing with the goal of extending DITA while allowing data interchange with other sites. This is further explained in Chapter 5.
Chapter 2 is about setting up your DITA environment. I did not set my systems up exactly the same way as Eliot did, but I made some changes after reading this chapter.
I wish I had been able to read Chapter 3 before I set up my company’s DITA prototype setup, because I would have set up new local Shell Document Types (DTD’s). It would have been better than modifying the existing DTD’s for our use. For instance, when we later opened files from our first DITA prototype, we could not immediately process them, because our DTD’s removes some elements that were used in those DITA files. By immediately setting up new DTD’s for our own use, we would have avoided that problem.
Chapter 3 has a lot of information for authors, but don’t skip it. Like most of the book, it is mainly for DITA implementers, and there is a lot of useful information squirreled away here that the authors don’t need. In particular, don’t skip the last half of this 100 page long chapter. Task steps for conditional processing (Authoring Step 15), and using DITAVAL’s (filtering) (Authoring Step 16) are hidden here. Guidelines for CCMS requirements are also hiding there.
In Chapter 4, you need to read “Introduction to Open Toolkit Customization and Extension”, pages 145-154, even if you have already written one or two plugins. It describes the XML elements of several plugin files. After reading it while creating my first plugins, I still refer to it occasionally.
When you are planning a new plugin, the examples at the end of Chapter 4 for HTML and PDF are required reading. They are sufficient to create simple working plugins, a bit more than what you need for “Hello World”.
Chapter 5, “Vocabulary Composition and Specialization”, tells how DITA creates the vocabulary of elements you use in your DTD’s. This is very useful background information, but to create a new DTD Shell yourself, you need the information in Eliot Kimber’s tutorials online, which will be in Volume 2 of this book. Read this chapter before you start, then keep it handy when you are using those aids. The last section, “DITA and Namespaces”, is academic material only useful when you care to know why DITA uses namespaces in some cases but not others.
Chapter 6 “Maps and Topics” is mainly theoretical. Skim it anyway. It starts by describing why the DITA approach is so different from previous XML document standards. It describes the importance of splitting topic order and linking (maps) from topic content, metadata use and precedence, generating several files from one input file and vice versa, and the various elements found in maps. You should find and read sections of it in detail when you use those parts of DITA.
Chapter 7, “General Structural Patterns in DITA” describes how DITA files are organized, presenting theoretical data for practical use. First key take-away: just because the DTD let’s you do it, doesn’t mean you can do it in DITA. This is a good summary of how DITA files are structured, and why these choices were made by the DITA standard. Read this chapter once.
Chapter 8, “Pointing to things: Linking and Addressing in DITA”, describes DITA’s various linking methods and how to use them. You need to know this, to allow you to constrain out only the elements your organization doesn’t need, and to help your writers.
Chapter 9, “Reuse at the Element Level, the Content Reference Facility”, is about reuse. My team avoided using conref’s until we had tried out DITA on a prototype project. That still seems like a good decision to me. Add it when you are comfortable with DITA.
Chapter 10, “Conditional Processing: Filtering and Flagging”, describes a topic that will inevitably arise in most writing teams. Again, like conref’s, we put it off at first. You need to learn how to do it, to implement examples, and help the team decide when to add it to your DITA implementation.
Chapter 11, “Value Lists, Taxonomies, and Ontologies: SubjectScheme Maps” is one I have only begun to understand. However, I think it addresses a problem I see at work, where we want to have different lists of “conditional” topics for different projects. I need to point it out to my Information Model Designer, and see if it solves our problem.
Appendix A: “Character Encodings, or What Does UTF-8 Really Mean?” presents useful information about character encodings. Kimber starts it as a rant, with the most useful information at the end of the chapter.
Appendix B: “Bookmap: An unfortunate design” is valuable reading for a Sunday afternoon, but in Technical Publications, you probably want to start out by using Bookmaps as the top map of your document. The bookmap should include only other maps, so it is one small file in each project. You can replace it with something better if you run into its limitations.
For the Information Model designer:
There is a lot of information here that isn’t in the books for DITA writers, but which is very useful, or required, for the Information Model designer.
If you are the Information Model designer, or the first DITA author on your team, you need to read Chapters 3, 6, 7 first. When you want to worry about links, read Chapter 8. Chapter 8 also introduces re-usable strings, because DITA uses the linking technology as one way to store strings. Because these strings can be used conditionally, as described in Chapter 10, Chapter 8 also spends a couple of pages describing Conditional Processing as it applies to keys.
For content reuse, read Chapter 9, about “conref’s”, the Content Reference facility. You use conref to reuse whole topics and common portions of a topic. This includes DITA’s second method for storing strings, this time strings that can contain other XML elements.
You will need to consider Chapter 11 when you have lists to track that are used in XML editing. This would include different lists for each of your projects to use for conditional processing.
Summary:
I find this book is often a better choice than searching the web, because it presents information that is not described or summarized as well in the DITA Users list or other venues. It has a mass of reliable, usable information. If you are a DITA developer, you need this book. If you are an Information Model designer, you will also find information here that you need and won’t get elsewhere. Your DITA developer will almost certainly forget to tell you about some of it, if they actually know about it. I know I found info while preparing this review that my Information Model designer needs!
Talk Software 