metabuilder/docs/development/quality/documentation-quality-checker.md

Documentation Quality Checker

A bash script that analyzes project documentation and provides a comprehensive quality score from 0-100%.

Overview

The Documentation Quality Checker evaluates your project across 8 key documentation metrics:

1. README Coverage - Presence of README files in main and subdirectories
2. Documentation Structure - Organized /docs directory with subdirectories and key files
3. Code Comments - Inline comments in source files
4. JSDoc Coverage - JSDoc/TypeDoc annotations in TypeScript/JavaScript files
5. Type Annotations - TypeScript strict mode and type usage
6. Examples/Guides - Example code, demo files, and test coverage
7. Architecture Documentation - Design, architecture, and implementation docs
8. Security Documentation - Security policies, guidelines, and LICENSE files

Features

• Simple to use: One-line command execution
• Detailed metrics: 8-point assessment framework
• Actionable recommendations: Specific suggestions for improvement
• Verbose mode: Optional detailed output with findings
• Quality ratings: Categorized results from CRITICAL to EXCELLENT
• Color-coded output: Clear visual formatting

Installation

The script is located in /scripts/doc-quality-checker.sh and is already executable.

Usage

Basic Usage

./scripts/doc-quality-checker.sh

Analyzes the current directory.

Analyze Specific Project

./scripts/doc-quality-checker.sh /path/to/project

Verbose Output

./scripts/doc-quality-checker.sh /path/to/project true

Shows detailed findings for each metric.

Output Example

╔════════════════════════════════════════════╗
║  Documentation Quality Assessment (0-100%) ║
╚════════════════════════════════════════════╝

Metrics:
  README Coverage                60%
  Documentation Structure        65%
  Code Comments                   0%
  JSDoc Coverage                100%
  Type Annotations               80%
  Examples/Guides                60%
  Architecture Docs              50%
  Security Docs                 100%

────────────────────────────────────────────
  OVERALL SCORE                  64%
────────────────────────────────────────────

Quality Rating: FAIR (60-74%)

Recommendations:
  - Increase inline code comments (5-10% density recommended)

Quality Ratings

• 90-100%: EXCELLENT - Comprehensive documentation
• 75-89%: GOOD - Well-documented with minor gaps
• 60-74%: FAIR - Moderate documentation coverage
• 45-59%: NEEDS IMPROVEMENT - Significant documentation gaps
• <45%: CRITICAL - Minimal or missing documentation

What It Checks

README Coverage (Max 100%)

• Main README.md in project root (+40%)
• Documentation index in /docs (+30%)
• READMEs in multiple subdirectories (+30%)

Documentation Structure (Max 100%)

• Organized /docs directory (+35%)
• Multiple documentation subdirectories (+30%)
• Key files: PRD.md, ARCHITECTURE.md, guides (+20%, +15%)

Code Comments (Max 100%)

• Percentage of files with inline comments
• Aims for 5-10% comment density

JSDoc Coverage (Max 100%)

• TypeScript/JavaScript files with JSDoc blocks
• Measures documentation of exported functions

Type Annotations (Max 100%)

• tsconfig.json presence (+50%)
• TypeScript strict mode enabled (+30%)
• Sufficient TypeScript files (>10) (+20%)

Examples/Guides (Max 100%)

• /examples directory (+40%)
• /docs/guides directory (+30%)
• Comprehensive test coverage (>10 tests) (+30%)

Architecture Docs (Max 100%)

• ARCHITECTURE, DESIGN, or IMPLEMENTATION documentation
• Each found document adds 25%

Security Docs (Max 100%)

• SECURITY.md file (+50%)
• LICENSE file (+25%)
• Security/authentication references in docs (+25%)

Recommendations

The script provides specific, actionable recommendations based on which metrics score below 60-70%:

• Low README: Add comprehensive README files to key directories
• Low Documentation Structure: Organize docs with a /docs directory and subdirectories
• Low Comments: Aim for 5-10% comment density in code files
• Low JSDoc: Add JSDoc comments to exported functions and interfaces
• Low Types: Enable TypeScript strict mode and add type annotations
• Low Examples: Create an examples/ directory with demo code
• Low Architecture: Write documentation about system design and decisions
• Low Security: Add SECURITY.md and document best practices

Integration

This script can be integrated into your CI/CD pipeline to:

• Track documentation quality over time
• Fail builds if documentation score drops below threshold
• Generate documentation reports
• Enforce documentation standards

Example CI Integration

- name: Check Documentation Quality
  run: |
    score=$(./scripts/doc-quality-checker.sh . | grep "OVERALL SCORE" | awk '{print $NF}' | tr -d '%')
    if [ $score -lt 50 ]; then
      echo "Documentation quality too low: $score%"
      exit 1
    fi

Requirements

• bash 4.0+
• find, grep, xargs (standard Unix utilities)
• wc for line counting

Performance

The script performs limited scans to avoid lengthy analysis:

• README check: Top 2 levels of directory structure
• Code analysis: First 50-80 files of each type
• Documentation scan: /docs directory only

Total execution time: typically < 5 seconds for most projects

Notes

• The script uses sampling for large projects to maintain performance
• It provides a quick health check, not an exhaustive audit
• Results can vary based on project structure and file organization
• Best used as part of ongoing documentation practices, not as a substitute for actual writing

Author

GitHub Copilot - MetaBuilder Project

License

Same as the MetaBuilder project (see LICENSE file)