Documentation health metrics

Purpose

Use this pair to answer: Is active documentation current, and can intended users complete the documented task without additional help? Freshness is a maintenance signal; task success is a usability outcome. A recently reviewed page can still be confusing, while an older stable page may remain highly usable.

Application

Use the measures for task-oriented documentation with an identified audience, owner, review cadence, and observable completion outcome. Separate content types with different volatility and task consequences.

What it is

• Documentation freshness measures whether active pages were reviewed within their assigned cadence.
• Documentation task-success rate measures whether representative users complete the documented task without unplanned assistance.

Together they distinguish maintenance compliance from user effectiveness. Neither measure should be optimized by deleting difficult pages, widening cadences, or choosing only experienced test participants.

Definition and components

Documentation freshness

Use this as the calculation definition: Active pages reviewed on time divided by Active pages requiring review. Unit: Percentage. Interpretation: Shows the share of active documentation reviewed within its risk-appropriate cadence at the cutoff date.

Documentation task-success rate

Use this as the calculation definition: Successful task attempts using the document divided by Observed attempts. Unit: Percentage. Interpretation: Shows the share of observed attempts in which intended users complete the defined task without unplanned additional help.