DMI — Documentation Maintainability Index - mehen

DMI summarizes how maintainable a Markdown file is as a repository artifact. It is the documentation analogue of the Maintainability Index for source code.

Formula

Components are first normalized to [0, 1], then combined:

DMI = clamp01(
      1
    − 0.18 · V_norm       (Markdown Halstead volume)
    − 0.18 · M_norm       (MCC)
    − 0.10 · R_norm       (MRPC)
    − 0.16 · L_norm       (Link Debt)
    − 0.10 · T_norm       (Table Burden)
    − 0.10 · A_norm       (Artifact Debt)
    − 0.10 · S_norm       (Poor Section Balance)
    − 0.12 · F_norm       (Filler / Lazy Risk)
    + 0.10 · G_norm       (Good Scaffold)
) · 100

Bands

DMI	Band	Meaning
85–100	Highly maintainable	Easy to extend; low review cost.
70–84	Good	Normal repository documentation.
50–69	Needs attention	Inspect top contributors.
30–49	Hard	Review burden is real.
0–29	Documentation debt	Likely refactor / split candidate.

DMI is not “usefulness”

A long, linear filler document can score respectable DMI while scoring high on Filler / Lazy Risk. A short dense architecture note can score low DMI but be extremely high-value. DMI measures maintainability burden, not value. The combined DMI × RCI × Filler Risk matrix (review criticality) is the canonical way to read DMI in context.

References

Oman, P. & Hagemeister, J. (1992). Metrics for assessing a software system’s maintainability. IEEE Conference on Software Maintenance — the source-code MI ancestor.

See also

Maintainability Index — the source-code analogue.
Filler / Lazy Risk — the orthogonal “is this filler?” axis.
Review Criticality Index — combines DMI with deltas.