Edit online

DITA Map Metrics Evolution

Radu Coravu
9 Sep 2022
Read time: 3 minute(s)
The DITA Map Metrics Report transformation scenario available in Oxygen can be applied on a DITA Map and produce all kinds of interesting metrics for your DITA project:
  • The number of processed maps and topics.
  • Content reuse percentage.
  • Number of elements, attributes, words, and characters used in the entire DITAmap structure.
  • DITA conditional processing attributes used in the DITA maps.
  • Processing instructions.
  • External links.
  • All @outputclass attribute values gathered from the DITA project.
There is also an open source DITA Open Toolkit plugin on the Oxygen XML GitHub organization which can be used to generate a metrics report either in HTML or XML format.

If you generate metrics for various stages in the history of your DITA project (for example for various releases) you can combine those metrics and generate graphs which can show various indicators like:

  • Fluctuations in number of topics and maps.
  • Fluctuations in content reuse.

Metrics reports and metrics evolution reports are useful to get an overview of a DITA-based documentation project and to discuss its future directions. They are also useful indicators to discuss with management.

Here are some steps to generate a metrics evolution report for a DITA project hosted on a Git server:
  1. Install this DITA Open Toolkit plugin which can publish DITA tables as SVG graphs: https://github.com/oxygenxml/dita-table-svg.
  2. Install the DITA Metrics report plugin in your DITA Open Toolkit installation (if not yet installed): https://github.com/oxygenxml/dita-ot-metrics.
  3. Switch your Git project to various tagged versions, after each switch apply the metrics-report-xml transformation type on the DITA Map and generate an XML file representing the metrics for that particular version. As an example I created 4 metrics reports for 4 previous Oxygen XML User's Guide versions: https://github.com/oxygenxml/dita-ot-metrics/tree/master/evolution/samples.
  4. Apply the provided XSLT stylesheet to generate a DITA topic containing tables which show how various indicators change between versions.
  5. Apply the DITA to HTML5 transformation on the topic to create an HTML document showing the evolution of different indicators as a graph.