DITA reporting tools in oXygen
Need some basic metrics on your DITA files? Wondering whether your topics are the right length or not? Check out this new feature in oXygen version 13.
There’s a new DITA Map Metrics report in oXygen v13. It provides information about your map file, the size of the topics, the elements you used, and more.
To run the report, you use a transformation scenario, so you first open the map (and make sure you select the root element of the map or you get a partial report, which was a surprising “feature”), and then select Document > Transformation > Configure Transformation Scenario.
Select the DITA Map Metrics Report and then Transform Now.
An excerpt of the result is shown below:
The report will tell you which elements you are using, the average length of your topics, and much more. It’s extremely useful for evaluating the completeness of a DITA map. For example, if the report shows lots of short topics with only a few words, that would tell you that those topics are probably incomplete. Conveniently, the list of shortest topics is linked to the source files, so you can click on the link and see the file immediately to figure out what to do.
George Bina of oXygen showed me this report at tekom in October. My advice was to charge extra for it, but you’ll be pleased to know that he ignored me and included the report in the regular product.
The report itself is generated by an XSLT file that runs through the DITA Open Toolkit. You could modify the XSLT to create your own custom report or extend what’s there.
I anticipate using this report quite heavily over the next year as I work on a new book.
About the author
Patrick Quinlan
Hi Sarah,
How cool! I had no idea this report existed. At Citrix, we developed a QA plugin that let’s you report on your content in a similar way, except that you can check terminology, conditions, tagging, and other stuff. It generates a color coded HTML report, and provides a dynamic pass/fail mechanism. We recently posted the plugin on sourceforge. You can see more information at ditanauts.org.
Patrick
Sarah
Hi!
I have been using the metrics report for almost a year now and I think that it’s a great analysis feature.
However, I would be delighted to find more information on what all of the metrics info mean. For example, in this article you say:”For example, if the report shows lots of short topics with only a few words, that would tell you that those topics are probably incomplete. Conveniently, the list of shortest topics is linked to the source files, so you can click on the link and see the file immediately to figure out what to do.”
Is there a sort of explanation of metrics report results somewhere that I haven’t found yet? Or if an explanation doesn’t currently exist, is there one in the works??
Thanks!
Sarah
Sarah O'Keefe
Hi Other Sarah,
I’m not aware of any explanations of the metrics, and my example is a case where I have extrapolated from the report to my own interpretation. But I think it’s fairly clear that a topic with 24 words is unlikely to be complete. 🙂