documentation-audit

Documentation Audit

A comprehensive documentation audit with two modes and a single tier:

Modes:

• Planning (before docs exist) — documentation strategy design, content type mapping, learning path architecture, scaffolding strategy
• Audit (on existing docs) — linguistic precision, structural taxonomy, pedagogical effectiveness, consistency, repository architecture, audience calibration, completeness and freshness

Single tier: Unlike security auditing, documentation evaluation is methodology-based (style guide application, framework classification, cognitive load analysis), not tool-licensed. Vale, markdownlint, and the analytical frameworks are all free/open-source. The value is in the analytical framework, not the scanner.

Core question: "Does this documentation teach effectively?"

Academic foundations

This skill synthesizes seven research threads into a single audit methodology:

1. Classical Composition (Strunk & White 1918/1959) — Omit needless words, active voice, positive form, specific/concrete language, parallel construction. The foundational linguistic layer beneath all documentation quality.

2. Enterprise Style Standards (Google Developer Documentation Style Guide; Microsoft Writing Style Guide) — Second person, conditions before instructions, timeless language, inclusive terminology, global accessibility. The enforceable ruleset layer with Vale automation support.

3. Structural Taxonomy (Procida, Diataxis Framework 2017+; augmented by Good Docs Project) — Four epistemic quadrants (Tutorial, How-To, Reference, Explanation) based on study vs. work and practical vs. theoretical axes. Quadrant pollution detection. Augmented with Good Docs Project templates for changelogs, READMEs, ADRs, troubleshooting, and migration guides.

4. Cognitive Load Theory (Sweller 1988; Chandler & Sweller 1992; Willingham 2009) — Intrinsic/extraneous/germane load taxonomy. Split-attention effect: code samples separated from their explanations force readers to cross-reference, consuming working memory. Guidance fading effect: novices need explicit scaffolding; discovery-style documentation actively harms new users. Forgetting curve (Ebbinghaus 1885): documentation must support elaborative retrieval, not just initial comprehension.