Module documentation_and_knowledge_metrics 

Documentation and Knowledge Metrics

This module measures whether the knowledge needed to safely maintain a codebase is actually documented and findable, not just whether documentation technically exists somewhere: does a new engineer, or an existing one working on unfamiliar code, have what they need to make a safe change, or does that knowledge live only in the heads of a shrinking number of tenured people. A system maintained for years by the same two engineers can function perfectly well with almost no written documentation, right up until both of those engineers leave within the same year — at which point the knowledge is discovered to have never been captured anywhere durable. That risk has a standard name in the industry: the bus factor (or truck factor).

Formula

Bus factor = the minimum number of people whose combined knowledge
             share meets or exceeds a critical threshold (commonly 50%)

At risk  when bus_factor <= minimum_safe_bus_factor

Why it matters

Documentation existence is not the same as documentation usefulness — counting wiki pages or READMEs tells you almost nothing about whether knowledge is actually accessible when needed. Bus factor measures the underlying risk directly: how concentrated is the knowledge needed to safely change a system. A low bus factor can hide behind apparent stability — a system that has not changed in years is not necessarily low-risk, it may simply not have needed its sole expert yet — and discovering the gap only during an emergency staff transition is exactly the expensive, avoidable failure mode this module exists to surface in advance.

Example

use software_engineering::documentation_and_knowledge_metrics::{
    bus_factor, is_bus_factor_at_risk,
};

// One person holds 60% of the knowledge share for a system: a single
// departure alone crosses the 50% critical threshold.
let concentrated = bus_factor(&[60.0, 25.0, 15.0], 50.0).unwrap();
assert_eq!(concentrated, 1);
assert!(is_bus_factor_at_risk(concentrated, 2));

// Five people each hold an even 20% share: it takes three departures
// to cross the same threshold.
let spread_out = bus_factor(&[20.0, 20.0, 20.0, 20.0, 20.0], 50.0).unwrap();
assert_eq!(spread_out, 3);
assert!(!is_bus_factor_at_risk(spread_out, 2));

Pitfalls

• Counting documentation existence rather than usefulness — tells you almost nothing about whether knowledge is actually accessible when needed.
• Never checking documentation staleness relative to how much the system has changed — risks actively misleading, out-of-date content.
• Mistaking apparent stability for low risk — a system that has not changed in years can mask a severe, undocumented bus-factor problem behind a system that simply has not yet needed its sole expert.
• Discovering critical undocumented knowledge only during an emergency staff transition — the expensive, avoidable failure mode this chapter is built to prevent.

Sources

• Chapter 4.6, Documentation and knowledge metrics.
• The “bus factor” (or “truck factor”) is a widely used, informally named industry concept for knowledge-concentration risk.

Topic doc: software-engineering-metrics/locales/en-001/chapters/04-06-documentation-and-knowledge-metrics.md

Functions

bus_factor

The bus factor: the minimum number of people whose combined knowledge share meets or exceeds critical_threshold_percent (commonly 50.0).

is_bus_factor_at_risk

Whether a bus factor is at or below a defined minimum-safe threshold (e.g. a bus factor of 1 or 2 is commonly considered dangerously low).