Docs Decay Velocity

Documentation Decay Velocity

Category: Documentation Time Saved: 2+ hours per documentation audit Battle-tested: Yes — observed across dozens of projects

The Problem

Your README says "47 unit tests" but you now have 89. Your docs say "requires Node 16" but the project uses Node 24. Your architecture diagram shows a service that was removed 6 months ago.

Why It Happens

Documentation decays at a rate proportional to how fast the code changes. Hardcoded numbers and specific versions rot fastest because they change with every release.

The Decay Hierarchy

Fastest decay (highest risk):

Slower decay (lower risk):

The Rule

Prefer runtime reads or dated stamps over hardcoded values.

Instead of Hardcoded Counts

<!-- ❌ WRONG — hardcoded count -->
This project has 47 unit tests ensuring quality.

<!-- ✅ BETTER — script-generated or dated -->
This project has comprehensive test coverage.
See test results: `npm test`

<!-- ✅ ACCEPTABLE — dated stamp -->
As of April 2026, we have 89 unit tests.

Instead of Version Requirements

<!-- ❌ WRONG — hardcoded version -->
Requires Node.js 16 or higher.

<!-- ✅ BETTER — point to source -->
See `engines` in package.json for version requirements.

<!-- ✅ ACCEPTABLE — checked at runtime -->
Requires Node.js (see .nvmrc for specific version).

Instead of Path References

<!-- ❌ WRONG — hardcoded path -->
Configuration is in `src/config/settings.ts`

<!-- ✅ BETTER — pattern description -->
Configuration files are in `src/config/`

<!-- ✅ EVEN BETTER — searchable hint -->
Search for `CONFIG_` constants for all settings.

Automation Strategies

1. Generate Docs from Source

// Read real count from test output
const testCount = execSync('npm test -- --json')
  .toString()
  .match(/(\d+) tests/)[1];

// Inject into template
const readme = template.replace('{{TEST_COUNT}}', testCount);

2. CI/CD Doc Validation

# .github/workflows/docs.yml
- name: Check doc freshness
  run: |
    # Fail if README mentions wrong version
    EXPECTED=$(node -p "require('./package.json').engines.node")
    grep -q "Node.js $EXPECTED" README.md

3. Dated Stamps for Manual Content

## Performance Benchmarks

*Last updated: April 2026*

| Operation | Time |
|-----------|------|
| Startup | 1.2s |
| Query | 45ms |

Red Flags to Grep For

# Find hardcoded numbers in docs
grep -rn '\b[0-9]\+ tests\b' docs/
grep -rn '\b[0-9]\+ endpoints\b' docs/
grep -rn 'Node\s*[0-9]\+' docs/

# Find likely-stale paths
grep -rn 'src/' docs/ | while read line; do
  path=$(echo "$line" | grep -oP 'src/[^\s`]+')
  [ ! -e "$path" ] && echo "STALE: $line"
done

Content Categories

Verification Checklist

• Search docs for hardcoded numbers
• Verify version requirements match package.json
• Check file path references still exist
• Add dated stamps to manually-maintained sections
• Set calendar reminder for quarterly doc review

Related Skills

• mermaid-mode-fragility — Diagram maintenance
• universal-audit-pattern — Documentation audits