Review: DITA for Practitioners, Volume 1: Architecture and Technology

Eliot Kimber has done a great job of compiling relevant, actionable guidelines and practices in the first volume of DITA for Practitioners. I fall into the “those with prior DITA experience” category. As a self-taught DITA (and XML, for that matter) user, I found a lot here that filled in the gaps in my knowledge. (Especially helpful was the section on essential terminology.) While I skimmed over some of the basic info in Chapters 2 and 3, new users will find a thorough explanation of how to get up running, writing and producing output with DITA and the Open Toolkit.

In later chapters, Eliot goes into how to install, run, and make basic customizations to the toolkit. Even though I’ve created lots of plugins, I’m certain I’ll come back to the sections where he explains extension points and best practices for creating ant targets. Part 2 builds on the foundation set in part 1, layering in complexities like specialization, compound maps, vocabularies, reuse, and more. (I’m still trying to wrap my brain around Chapter 8 on linking and addressing.)

In short, I wish I’d had this book when I started out implementing DITA four years ago. I’m certainly glad I have it now.

Python, LXML, and setting xml:lang

Having trouble figuring out how to script the @xml:lang attribute?

For a DITA document that contains a single language, the highest level element (i.e. map, concept, task, etc.) that contains content should set the @xml:lang attribute to the language that applies to the document.

The question: How do I set the @xml:lang attribute using lxml? Everyone seems confused on the forums. Continue reading

Impressions from DITA NA 2012

DITA NA 2012 has come and gone. This year the conference boasted a record 318 attendees. They added an emerging technologies track. It was held in beautiful San Diego.

I’ve presented at this conference for the last several years, and my impression this year is that the level of discourse has noticeably risen. There were more topics that were more technical. Presenters discussed more best practices, more concrete experiences, and more practical advice than in years past, when many discussions were more or less theoretical. Instead of “this is what will/might/should happen,” I heard more of what did happen and is happening. It sounds cliche and, yes, self-serving to say it, but this is an exciting time to be “in” DITA.

For me, these were the highlights of the conference:

  • Steve Anderson mentioned the QA plugin in his presentation “Automation and testing DITA OT Content and Customizations”! I was totally stoked.
  • George Bina showed us his RelaxNG plugin, which reproduces the DITA DTDs in an easier to manipulate format. By combining RelaxNG with Schematron, you can deeply customize your authoring experience, both constraining elements and attributes and providing in-line guidelines to authors.
  • Michael Boses also discussed the awesomeness of Schematron. Ok, fine, I’m convinced. We’ll rewrite the QA plugin in Schematron.
  • Bryan Schnabel showed his XLIFF round trip plugin, which converts DITa to and from XLIFF. Just converted a document to XLIFF. It was glorious. I am going to be all over this one.
  • Mat Verghese from Citrix discussed a detailed and solid vision for raising the value and esteem of Content Strategists
  • Keith Schengili-Roberts, in his keynote, gave me some great ideas for additions to the QA plugin, like calculating Flesch-Kincaid reading scale values. More to come on that front.
  • Mark Baker discussed the use cases for his SPFE architecture, which is a different solution to many of the problems DITA implementors face. I particularly liked the idea of automagically creating links based on string matches. It’d be cool if the QA plugin’s link report could suggest new links based on the content….hmmm…
  • I learned you can directly style XML with CSS! Who knew? There must be some great applications for this.
  • And of course, Eliot Kimberly released his new book on implementing DITA. I’ll be posting a review sooner rather than later.

All told, a great conference.

QR Codes in DITA Ouput

Inspired by a thread started by Sean Healy, and building on the instructions posted by Kevin Brown, I added the ability to generate and insert QR Codes into PDF output to the mypdf plugin.

I ignore QR Codes in marketing, but I think they could be a great way to link to resources, such as videos, from printed technical documents. Readers can simply zap the codes with their phones to pull up the content.

Continue reading

Example Constraints Plugin

One of the most important features, in my opinion, of DITA 1.2 is the constraints mechanism. In short, constraints let you reduce the elements and attributes available to your authors. You can also specify when elements/attributes are required, and which tag structures are legal (and, therefore, which are illegal). Eliot Kimber wrote a great tutorial on how to set up constraints, but if you’d like an example plugin, you can download the one I’ve created off sourceforge.

Continue reading

Recursive DITA parsing using Perl and XML Twig, Part I

If you’re doing any text parsing and manipulation, it’s hard to ignore the processing power of Perl—especially considering that it comes pre-installed on the basic OS X platform.   There are several XML parsing modules out there and plenty of sites comparing the features and usability of each one.

Personally, I like Michael Rodriguez’s (mirod) Twig module.   It’s available on CPAN here. Continue reading

Reporting on your DITA repository with PowerShell

As a long-time Unix bigot, it pains me to say but I have to be honest: I really like PowerShell, Microsoft’s new-ish scripting language. In fact, it has an advantage over Unix shell scripting languages in that it is fundamentally based on objects rather than on strings. Now what else do I use daily that is object-based? XML of the DITA kind, of course.

While there are a number of good articles on using PowerShell with XML, I thought I’d take you through a use case specifically with DITA. Continue reading

Automagically Check Tagging, Terminology, and More

If you have more than one writer on your team (and perhaps if you have exactly one), enforcing terminology, tagging, and other standards can be challenging. We wanted an easy way to catch simple issues, like lists nested inside paragraphs and the use of out-of-date console names. We also wanted to verify, across a large document set, that certain DITA attributes were used correctly in order to make our output as reliable as possible. We started with a PowerShell script written by Ben Colborn, which included a large number of xpath-based quality assurance checks. We’ve since ported those checks into an open toolkit plugin, and we are happy to say we can now share it here on sourceforge.

Continue reading