Skip to main content
MCC estimates local reading burden caused by flow breaks, nesting, context switches, and dense artifact clusters. It is the documentation analogue of cognitive complexity for source code.

​
Base weights

Each construct contributes a base weight, ranging from 0.20 for a normal heading-level increment up to +4.00 for a verified broken external link.

​
Formula

The MCC formula has three multiplicative layers: 
MCC_positive = Σ base_weight(c) · nesting_multiplier(c) · clustering_multiplier(c)

MCC = max(0, MCC_positive − min(Σ scaffold_credit(a), MCC_credit_cap))

​
Nesting multiplier

nesting_multiplier = 1 + 0.18 · nest(n)
Smaller than code-oriented nesting penalties because Markdown nesting is cheaper than control-flow nesting.

​
Artifact clustering multiplier

Dense clusters of artifacts in a 20-rendered-line window increase local switching cost.

​
Scaffolding credit

Well-labelled, bounded, locally explained artifacts earn credit capped at 0.25 · MCC_positive. Credit applies only when label, nearby explanation, and bounded size are all present.

​
Interpretation

MCCMeaning
0–10Easy to read.
11–25Normal.
26–50Dense.
> 100Documentation subsystem rather than one page.

​
References

  • Campbell, G. A. (2018). Cognitive Complexity — A new way of measuring understandability. SonarSource white paper — the design ancestor. PDF.
  • Sweller, J. (1988). Cognitive load during problem solving: Effects on learning. Cognitive Science 12(2): 257–285 — basis for the nesting and clustering multipliers. DOI.
  • Mayer, R. E. (2009). Multimedia Learning, 2nd ed. Cambridge University Press — split-attention and contiguity principles behind the artifact-clustering penalty.

​
See also