DITA 101, second edition, by Ann Rockley and others is one of the best tool-independent books about DITA. It’s a good primer to learn about DITA in a couple of hours.
Strong context
The book excels in firmly embedding DITA’s technologies and workflows in the larger contect of structured writing and topic-based authoring.
“The value of structure in content,” the second chapter, illustrates structured writing with the obvious example of cooking recipes. Then it goes on to show you how to deduce a common structure from three realistically different recipes – which I hadn’t seen done in such a clear and concise way.
“Reuse: Today’s best practice,” the third chapter, takes a high-level perspective. First it acknowledges organizational habits and beliefs that often prevent reuse. Then it presents good business reasons and ROI measures that show why reuse makes sense.
Comprehensive, solid coverage
From the fourth chapter on, Rockley and her co-authors describe DITA and its elements very well from various angles:
- “Topics and maps – the basic building blocks of DITA” expands on the DITA specification with clear comments and helpful examples.
- “A day in the life of a DITA author” is very valuable for writers who are part of a DITA project. Writing DITA topics and maps is fundamentally different from writing manuals, and this chapter highlights the essential changes in the authoring workflow.
- “Planning for DITA” outlines the elements and roles in a DITA implementation project for the project manager. Don’t let the rather brief discussion fool you: Without analyzing content and reuse opportunities, without a content strategy and without covering all the project roles, you expose your DITA project to unnecessary risk.
- “Calculating ROI for your DITA project” has been added for the second edition. It’s by co-author Mark Lewis, based on his earlier white papers: “DITA Metrics: Cost Metrics” and “DITA Metrics: Similarities and Savings for Conrefs and Translation“. It expands on the ROI discussion of chapter 3 and creates minor inconsistencies that weren’t eliminated in the editing process.
- “Metadata” first introduces the topic and its benefits in general and at length. Then it describes the types and usefulness of metadata in DITA. This might seem a little pedestrian, but it’s actually helpful for more conventional writers and for managers. It ensures they fully understand this part of DITA which drives much of its efficiencies and workflows.
- “DITA and technology” explains elements and features to consider when you select a DITA tool, content management system or publishing system. This always tricky to do in a book as much depends on your processes, organization and budget. While the chapter cannot substitute for good consulting, it manages to point out what you get yourself into and what to look out for.
- “The advanced stuff” and “What’s new in DITA 1.2” continue the helpful elucidation of the DITA specification with comments and examples that was begun in the “Topics and maps” chapter.
Mediocre organization
For all its useful contents, the book deserves better, clearer organization!
- Redundancies and minor inconsistencies occur as concepts are defined and discussed in several places. For example, topics are defined on pages 4, 24 and 46. The newly added ROI chapter complements the ROI points in the third chapter, but neither has cross-references to the other.
- The index doesn’t always help you to connect all the occurrences and navigate the text.
- Chapters are not numbered, yet numbering of figures in each chapter starts at 1. It’s not a big problem, because references to figures always refer to the “nearest” number, it’s just irritating.
Formal errors
The book contains several errors which add to the impression of poor production values. They don’t hurt the overall message or comprehensibility, but they are annyoing anyway:
- Mixed up illustrations such as the properties box in Word (page 72) vs. the properties box from the File Manager (73)
- Spelling errors such as “somtimes” (1) and “execeptions” (16)
- Problems with articles such as “a author” (20) and or a system that “has ability to read this metadata” (77)
- Common language mistakes such “its” instead of “it’s” (52)
Lack of competition
Another reason why it’s still one of the best books on the topic is that there simply aren’t many others!
- Practical DITA by Julio Vazquez is the only serious contender, and its practical, in-the-trenches advice complements Rockley’s book very well.
- [More books are pointed out in the comments, thanks everybody! – Added January 11, 2010.]
- DITA Open Toolkit by “editors” Lambert M. Surhone, Mariam T. Tennoe, Susan F. Henssonow is a compilation of Wikipedia articles. Amazon reviewers call other titles produced by the same editing team and publisher a scam.
Of course, several other honorable and worthwhile books include articles or chapters on DITA and/or discuss DITA in context of specific tools.
My recommendation
Despite its shortcomings, the book’s own claim is valid: “If you’re in the process of implementing DITA, expect to do so in the future, or just want to learn more about it without having to wade through technical specifications, this is the book for you.”
I recommend that you read it if you are
- Involved in a project to implement DITA
- Writing or translating documentation in a DITA environment
- Managing technical writers
Your turn
Have you read this book? What’s your opinion? Can you recommend other books or resources about DITA? Feel free to leave a comment!
Filed under: articles, books, DITA, managing, metrics, single sourcing, structured writing, technology, topic-based authoring | Tagged: ann rockley, Julio Vazquez, mark lewis |
Kai's Tech Writing Blog 
It is my understanding you missed this DITA book:
“Introduction to DITA: A User Guide to the Darwin Information Typing Architecture”
by Jennifer Linton & Kylene Bruski
http://www.comtech-serv.com/dita2.shtml
Marie,
While you’re correct about Kai not mentioning Introduction to DITA, that book is now a little dated and does need an update. The Arbortext version might be a little more current.
Thanks, Marie-Louise and Julio, for pointing out the two books. I actually didn’t know about either one, so these are valuable additions! The Arbortext version that Julio mentions can be found at http://www.comtech-serv.com/arbordita.shtml#book
Everyone is a promoter, today. That’s the lesson I got from the comments section of this post. I’d love to see comments about the content of the book. LOL
Good write up, Kai. I’m revisiting some of my favorite sites today. Yours is one of my regular stops. Thanks for contributing.
Thanks, Scott, I’m glad and proud to give back to our lively and engaging community from which I learn so much.
I am beginning to think that the context-free writing style dictated by DITA’s re-usability mandate is a bit of a poison pill swallowed by all authors writing about DITA. All I have found so far are documents with no cohesiveness, no overview or foundation. Just lots of random details strung together and I am left to try to piece them into an understanding of the whole. If I read one more explanation that specialization means you can specialize and that the specialized thing is related to the original thing but more specialized WITHOUT ever explaining how you use the original thing or what that specialization gives you, I will scream.
Does this book actually get to the nitty gritty? Or is it all marketing speak about what one COULD do if one could actually find a book that explains anything.
Hi, Grant, thanks for your comment. I agree, some of the writing about DITA can be quite free-floating and hence hard to understand. Ray Gallon and Mark Baker have railed against such context-free writing recently and shown that it hurts successful documentation. See their blog posts:
http://humanistnerd.culturecom.net/2013/01/08/lets-break-a-tech-comm-rule/
http://everypageispageone.com/2013/01/08/confusing-analytic-and-synthetic-truths-in-defining-topic-types/
However, I don’t think that is DITA’s fault which allows and even encourages context information in the element and to a lesser element in the element.
I’ve also found that DITA is harder to understand without a background and experience in topic-based authoring. The way I see it, DITA is just an architecture, a specific XML implementation, of topic-based authoring. Maybe that’s why a lot of stuff on DITA is long on reference-like details, but short on methodology.
That said, I would recommend “DITA 101” more for managers and anyone seeking a high-level overview. For nitty gritty instructions on how to implement DITA, I find “DITA Best Practices” more useful. See my review at
https://kaiweber.wordpress.com/2012/07/16/dita-with-confidence-dita-best-practices-book-review/
The book’s web page also shows the table of contents so you can gauge whether it offers the level of detail you need:
http://www.ibmpressbooks.com/store/dita-best-practices-a-roadmap-for-writing-editing-and-9780132480529
Hope this helps, Kai.
Thank you for the thorough response (as only a tech writer would).
I happen to be the inventor of a topic-based XML Schema for educational content (www.demml.org). However, I am trying to learn DITA for writing technical documentation and as a way to get better paying jobs as a technical writer. I have read hundreds of pages of documentation about DITA without a single mention of what the actual DTD is. (Just sample lists of some of the allowed elements, with no specifics on how they are to be structured.) How one actually creates a specialization. How one defines a “configuration.” I only accidentally stumbled on a few sentences that even state what a “configuration” is and how it is related to a “datatype shell.” Every document I can find just goes straight to the detail but with no context. I told a friend it is like being dropped into some isolated place in the world, put in a box, and trying to figure out where you are by looking at one piece of bark and two grains of sand. It is maddening.
And I do NOT have difficulty understanding data standards or complex systems. I taught myself XML Schema and devised my DEMML standard. I figured out RDFa and even wrote documentation that describes it more simply than the guys in the W3C working group thought was possible.
But one can only understand what one can get information about. I will work on reading through some DITA book or the specification for an hour or so until my brain becomes absolutely exhausted. Every single paragraph assumes I know absolutely every other term used in DITA but when I look up those terms, they aren’t really explained at all. Not to mention the esoteric terms used in many paragraphs which are often not used anywhere else. It is as if the specification is 1,200 pages of people trying to pretend they were writing documentation but intentionally telling you nothing at all. The grammar and English usage is often terrible so I can’t tell exactly what they are trying to say. Almost as if the whole thing was contracted out to non-native English speakers, a paragraph at a time, with not a single author having any idea what any other author was doing.
Yes, it is possible to write good documentation using DITA. It is also possible to write good documentation using Cuneiform on clay tablets. My problem is not with the standard (at least what I can figure out about it). My problem is with the “best practices.” While the best practices book seems to be relatively well written, the mindset it espouses virtually requires each and every paragraph to be an island unto itself. It must be utterly reusable in every possible context. This then, requires each paragraph to have no context whatsoever. Almost as if it is nothing but a glossary entry. In fact, most of the documents I have read read more like a randomly organized glossary than an actual document. I have even read the sections of DITA for Practitioners that are available for free. Every once in a while it will seem as if the author is about to reveal some real, useful, organized information, and then he goes off down yet another rabbit trail of random, not-quite-cohesive detail.
Sooo, given the insane and inane nature of all the DITA documentation I have read so far, I despair of ever finding a book or document that is not exactly the same. I don’t want to have to buy and slog through every book out there, hoping beyond hope that THIS ONE will be different. This one will actually be worth the money.
I am looking for a book that tells me exactly how to structure a Topic. What the top-level element must or can be. Exactly what elements are allowed inside each element. Clearly and concisely. Exactly all the metadata that is allowed, where. What that metadata instructs the processor to do and how much freedom a processor is allowed in how it handles everything. Also, what processors are available, how are they configured and how can they be modified to suit my needs. Is that too much to ask?
So, if the DITA 101 book is actually only a “high-level overview,” – in other words, nothing more than the repetitive non-information I have found so far – then it is certainly not the book I am looking for. The Best Practices book is available free online through the Berkeley Library. It really just talks about how to write content in this new write-forever-but-say-nothing-at-all style. I want a book with specifics. Specifics that are actually organized within the context of the specific that came before it and the specific that will come after it. Do you perhaps have anything you can recommend? Or do I get to make myself rich and famous by writing the first DITA book EVAR that is actually readable and useable. …
… If I can ever figure this stuff out, that is.
Hi, Grant, I don’t know that the type of book exists that you’re looking for. BUT: I’ve found all we needed by reading the DITA Best Practices book for guidance and advice, together with the DITA 1.2 Language Reference at http://ditainfo.info/DITA12langref/index for the technical details, such as “How to structure a Topic. What the top-level element must or can be. Exactly what elements are allowed inside each element. Exactly all the metadata that is allowed.”
Incidentally, the list of DITA books at http://www.ditawriter.com/dita-books/ has recently been updated and is the most comprehensive bibliography I know.
Hope this helps, Kai.