Documentation matches current version
Why it matters
Documentation that describes a v1 API in a project now on v3 is worse than no documentation: it actively sends developers down paths that no longer exist. A 'npm install package@1.2.0' command in the README when the current version is 3.0.0 installs broken software. Code examples showing deprecated methods produce runtime errors with no obvious cause. iso-25010:2011 analysability requires that documentation reflect the actual current system, not a historical one. For vibe-coded projects that iterate rapidly, docs are frequently written once for an early version and never updated as the API evolves.
Severity rationale
High because stale documentation sends developers down dead-end integration paths, producing runtime errors from deprecated or removed APIs that cannot be resolved without reading source code.
Remediation
Audit all code examples and install commands against the current version. Add a CI grep to catch pinned old versions in docs:
# Add to package.json scripts or CI
grep -rn "npm install.*@[0-9]" docs/ README.md || echo "No pinned versions found"
For projects maintaining multiple versions, use version selectors or version-specific branches (docs/v2/, docs/v3/) rather than a single unversioned doc set. Template install commands to pull the current version from package.json rather than hardcoding. Every deprecated method mentioned in docs must include a 'removed in vX, use Y instead' annotation.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the Developer Documentation Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · maintainability.analysability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from developer-documentation·automated