Links updated 21 January 2010
One sign that a book has succeeded is when it changes your perception of the subject. By that definition, Julio Vazquez’s Practical Dita (102 pages, lulu.com, now available on Amazon.com) succeeds. I have to say up front that my opinion of DITA was not enhanced by reading his book. However, the book is not at fault; it simply reveals some cringe-inducing aspects of DITA that I hadn’t seen before. I won’t dwell on those aspects in this review, except to say that I’m still scratching my head over why, in an age of semantic markup, DITA needs tags for italics and bold.
Practical Dita is targeted at readers who want an introduction to DITA, both the philosophy and basic usage. It does not cover some of the more advanced aspects of DITA, like specialization, and it is not a reference. Instead, it aims to get you started down the path to understanding DITA. The book assumes some basic knowledge of XML, but nothing particularly deep. If you are comfortable looking at angle brackets and HTML markup, you can probably dive right in.
Practical Dita begins with some basics on technical writing that draw you into the DITA philosophy. Unlike some schemas, an understanding of the philosophy behind DITA helps you work with it. Vazquez explains the DITA approach starting from basic concepts of technical writing. This may strike more experienced writers as superfluous, but it does help lay out the philosophy behind DITA.
After a short digression into content reuse, he describes the three topic types (concept, task, and reference) with examples. I thought this was the meat of the book, though I would have been happy with more detailed examples. In particular, it would have been nice to have some complete example so readers could see topics in context.
The book also covers inserting graphics, creating a DITAMAP, and using filtering and flagging. Appendices provide pointers to tools and additional information.
Overall, I think Practical Dita is a useful book for readers who want to dip their toes into the DITA stream and get started. It could have used another editing pass, a little more meat, in particular some detailed examples, and the print formatting reveals some of the limitations in the current version of the DITA Open Toolkit. That said, I liked this book. It sets a clear goal, for a specific audience, and achieves that goal; that’s rare.
[…] The short review is that if you are brand new to DITA, but understand at least a little bit about markup languages (basic HTML is probably enough), this is a good place to start. It is a short excursion through the DITA philosophy and basic usage. For my full review, go here. […]
The reason that DITA has <i> and <b> and other non-semantic markup tags is that it is deliberately built upon pre-existing HTML tags at the base level. This facilitates migrating content from web pages to DITA, even though it does not enrich the XML in a meaningful way. The web content has to be XHTML-conformant before it is migrated to DITA. You can find information on migration strategies online by searching on “migrate HTML to DITA”.
sorry, I should have escaped those tags for italic and bold in my comment, what I was trying to convey is “The reason that DITA has italic and bold and other non-semantic markup tags…”
To: D. Hoskins,
Thanks for your note (I edited your first comment to escape the italic and bold tags).
I see the point, though it concerns me that authors can so easily fall back on those tags. I guess if I were doing a specialization, the first thing I’d do would be to remove the representational tags. I’ll check out the search you recommend.
If something is a standard it typically contains more than anyone needs to make everyone happy. And this is the implementation task: understand the standard, take what you need to achieve your goal and drop what will be hazardous in your circumstances. Maybe you know this one: A fool with a tool stays a fool. Do not expect DITA or any standard to change the whole world to be good. The law of thermodynamics expects you to invest energy to fight the chaos. And dropping the domain that contains underline, bold, italic, superscript and subscript is even less than a specialization, it is a matter of configuration.
By the way: I do allow these tags but I render the text in orange in the XML editor as a warning. I know that engineers who know and use these tags typically have no idea what semantically meaningful tag I expect them to use. In 80% of the abuse I can correct and in all others I have to ask. Without those tags the words would be untagged forever. Not a good solution eihter, is it?
To: Gunnar Krause,
Thanks for your comment.
I like your idea of rendering the text in orange to call out tags that need attention. And, I agree that no standard is going to fix the world’s problems. I just don’t want a standard to perpetuate problems, and I think leaving tags that are solely representational does that.
There is a trade-off between allowing, then “correcting,” this kind of markup versus not allowing it, but possibly getting other kinds of tag abuse. Given that trade-off, I prefer the second choice, at least with professional writers, though that may put me in the minority.
I work with a large group of professional writers. The information architecture team has considered removing the presentation tags to avoid abuse. However, they may be more useful left in.
Many of our writers have not done structured authoring, or they are such experienced writers that their first reaction to DITA is that it’s too restrictive and they’ll find a way to do things the way they’ve always done them. To identify the need for remedial training, or even to identify the need for a specialization or different output rendering, I think we’ll keep tags like i and b. Automated searches for presentation tags in DITA can make them serve as a “honeypot” either for tag abuse or to identify an unidentified need.
[…] !wosdocs Review of "Practical DITA": https://xmlpress.net/2009/03/31/practical-dita-book-review/ […]
[…] start. It is a short excursion through the DITA philosophy and basic usage. For my full review, go here. This entry was posted in Book Review and tagged DITA. Bookmark the permalink. ← Feeding […]