DITA Metrics Definitions

Return to DITA Metrics Help Main Page Return to DITA Metrics Basic Help Main Page

Clarification of "Referenced"

DITA metrics is a notoriously confusing domain of knowledge. Apparently the human brain is not well suited to understanding abstract notions of web-like systems.

In the DITA and "DITA Metrics Module" context "referenced" means a block of text that appears in published output through a CONREF, also know as a Content Reference. That seems simple enough! How could there be a problem?

File structure is important

Suppose we have a file structure supporting conrefs that looks like this:

>

The total number of referenced words in this case is 3,000. All referenced words are collected in a "Common" directory and all CONREFs point to a location in "Common". The only way words in "Common" can appear in the published output is through a CONREF.

But a small change in how the information is organized can make a big change in the number of referenced words, like so:

>

Suddenly we have a a 25% drop in the number of referenced words. The reason is easy to see in the graphics above. Instead of all CONREFs being in a "Common" directory, they now appear in a published document. Therefore, to get the same published output we only need six CONREFs, not eight. That's where the 25% went.

Best Practice Related to CONREFs

Samalander recommends that all chunks of text that are CONREF'd be stored in a directory like "Common". The chunks are then much easier to find and all of your metrics will be more reliable.