Skip to main content

Documentation Health Monitoring

Status: Active
Version: 1.0.0
Last Updated: 2025-12-18
Related: E5:S02:T03

Overview​

Documentation health monitoring provides comprehensive visibility into the quality, consistency, and currency of documentation across the project. The health dashboard aggregates metrics from link validation, consistency checks, and review workflows to provide actionable insights.

Health Metrics​

Metric: Link Health Percentage
Calculation: (Valid Links / Total Links) × 100
Weight: 40% of overall health score

Components:

  • Total links (internal and external)
  • Valid links
  • Broken internal links
  • Broken external links
  • Files with broken links

Target: ≥ 95% link health

Consistency Health​

Metric: Consistency Score
Calculation: 100% - (Files with Issues / Total Files) × 100
Weight: 40% of overall health score

Components:

  • Version inconsistencies (Epic/Story version mismatches)
  • Cross-reference inconsistencies (broken references)
  • Terminology inconsistencies (inconsistent term usage)

Target: ≥ 90% consistency score

Review Coverage​

Metric: Review Coverage Percentage
Calculation: (Files Current / Total Files) × 100
Weight: 20% of overall health score

Components:

  • Files current (reviewed within cadence)
  • Files needing review
  • Critical docs needing review
  • High-priority docs needing review
  • Standard docs needing review
  • Low-priority docs needing review

Target: ≥ 80% review coverage

Overall Health Score​

Calculation: Weighted average of component scores

  • Link Health: 40%
  • Consistency Score: 40%
  • Review Coverage: 20%

Health Status Levels:

  • Excellent (≥90%): 🟢 Documentation is in excellent condition
  • Good (75-89%): 🟡 Documentation is in good condition with minor improvements needed
  • Fair (60-74%): 🟠 Documentation needs attention and improvements
  • Poor (40-59%): 🔴 Documentation requires significant improvements
  • Critical (<40%): ⚫ Documentation is in critical condition

Dashboard Usage​

Running the Dashboard​

# Basic usage (console output)
python3 scripts/documentation/documentation-health-dashboard.py

# Generate JSON metrics
python3 scripts/documentation/documentation-health-dashboard.py --output dashboard.json

# Generate human-readable report
python3 scripts/documentation/documentation-health-dashboard.py --report dashboard.txt

# Both JSON and report
python3 scripts/documentation/documentation-health-dashboard.py --output dashboard.json --report dashboard.txt

# Custom documentation path
python3 scripts/documentation/documentation-health-dashboard.py --path docs/architecture/

Dashboard Output​

JSON Output (--output):

  • Complete metrics data
  • Timestamp and path information
  • Link metrics (total, valid, broken)
  • Consistency metrics (inconsistencies by type)
  • Review metrics (coverage, files needing review)
  • Health score and status

Report Output (--report):

  • Human-readable dashboard
  • Overall health score and status
  • Detailed metrics by category
  • Recommendations for improvement

Integration with Workflows​

Release Workflow (RW)​

RW Step 9: Run Validators

  • Run documentation health dashboard
  • Include health metrics in release validation
  • Fail release if health score < 60% (critical threshold)

Update Kanban Workflow (UKW)​

UKW Step 6: Update Kanban Board

  • Include documentation health status in board metadata
  • Track health trends over time
  • Flag documentation issues for prioritization

CI/CD Integration​

Automated Health Checks:

  • Run dashboard as part of CI pipeline
  • Generate health reports on each commit
  • Track health trends over time
  • Alert on health degradation

Health Monitoring Procedures​

Daily Monitoring​

Automated Checks:

  • Link validation (internal links only)
  • Consistency checks (version, cross-reference, terminology)
  • Review status tracking

Actions:

  • Review dashboard output
  • Address critical issues immediately
  • Track health trends

Weekly Monitoring​

Comprehensive Checks:

  • Full dashboard generation
  • External link validation
  • Review workflow analysis
  • Health score calculation

Actions:

  • Review comprehensive health report
  • Prioritize improvements based on health score
  • Update documentation as needed
  • Track health trends

Monthly Monitoring​

Deep Analysis:

  • Historical trend analysis
  • Root cause analysis of recurring issues
  • Documentation improvement planning
  • Health score target setting

Actions:

  • Generate monthly health report
  • Analyze trends and patterns
  • Plan documentation improvements
  • Update health monitoring procedures

Health Improvement Workflow​

1. Identify Issues​

From Dashboard:

  • Review broken links
  • Review consistency issues
  • Review files needing review
  • Review overall health score

2. Prioritize Improvements​

Priority Levels:

  • Critical: Health score < 40%, blocking issues
  • High: Health score 40-59%, significant issues
  • Medium: Health score 60-74%, moderate issues
  • Low: Health score ≥ 75%, minor improvements

3. Create Tasks​

Kanban Integration:

  • Create Feature Requests (FR) for improvements
  • Create Bug Reports (BR) for broken links/issues
  • Assign tasks based on priority
  • Track improvements in Kanban

4. Implement Improvements​

Fix Process:

  • Fix broken links
  • Resolve consistency issues
  • Complete documentation reviews
  • Update documentation as needed

5. Verify Improvements​

Validation:

  • Re-run dashboard
  • Verify health score improvement
  • Confirm issues resolved
  • Update Kanban tasks

Health Score Targets​

Project-Level Targets​

Minimum Acceptable: 60% (Fair)

  • All critical documentation reviewed
  • No blocking broken links
  • Major consistency issues resolved

Target: 75% (Good)

  • Most documentation reviewed
  • Few broken links
  • Minor consistency issues

Stretch Goal: 90% (Excellent)

  • All documentation reviewed
  • No broken links
  • No consistency issues

Framework-Level Targets​

Minimum Acceptable: 75% (Good)

  • Framework documentation in good condition
  • Critical docs reviewed regularly
  • No major issues

Target: 90% (Excellent)

  • Framework documentation excellent
  • All docs reviewed on schedule
  • No issues

Metrics Tracking​

Track Over Time:

  • Health score trends
  • Link health trends
  • Consistency score trends
  • Review coverage trends

Analysis:

  • Identify improvement patterns
  • Detect degradation early
  • Plan maintenance cycles
  • Measure improvement effectiveness

Reporting​

Monthly Reports:

  • Health score summary
  • Issues identified and resolved
  • Improvement recommendations
  • Trend analysis

Quarterly Reports:

  • Comprehensive health assessment
  • Historical trend analysis
  • Improvement planning
  • Resource requirements

References​

  • Documentation Maintenance Policy: docs/architecture/standards-and-adrs/documentation-maintenance-policy.md
  • Documentation Review Cadences: docs/architecture/standards-and-adrs/documentation-review-cadences.md
  • Documentation Update Triggers: docs/architecture/standards-and-adrs/documentation-update-triggers.md
  • Epic 5: docs/project-management/kanban/epics/Epic-5/Epic-5.md
  • Story 2: docs/project-management/kanban/epics/Epic-5/Story-002-documentation-quality-assurance.md

Decision Record​

Decision: Implement comprehensive documentation health monitoring with dashboard, metrics, and procedures.

Rationale:

  • Provides visibility into documentation quality
  • Enables proactive maintenance
  • Supports data-driven improvements
  • Integrates with existing workflows
  • Tracks health trends over time

Consequences:

  • Requires regular dashboard execution
  • Needs integration with workflows
  • May require additional tooling
  • Provides actionable insights