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.

All told, the plugin includes about 100 quality checks, which you can customize to your needs. You will need to write xpath expressions—for which there are several online resources. Running a map through the plugin generates a report in HTML, which summarizes the errors by type, then lists them per-file. (To customize the checks, simply edit qachecks.xsl).

The plugin is great for daily quality assurance tasks, but you can also use it to prepare for a transition to a set of DITA constraints. Let’s say you began your implementation pre-DITA 1.2 and have a bunch of “legacy” data. Now you want to adopt 1.2 and have devised a set of constraints. You can describe element structures, via xpath within the plugin, that do not comply with your new constraints, then process your documents to see how much work you’ll need to do to get your old document in line with the new constraints. We imagine you could then automate some or all of the conversion based on the results. (Hmm.. that sounds like a new plugin idea…)

We have more posts on the QA plugin planned; in the meantime, if you have any questions, don’t hesitate to post them in the comments section.

Leave a Reply

Your email address will not be published. Required fields are marked *