GITHUB DOCUMENTATION WORKFLOW

Overview

The GitHub Documentation Workflow is an automated system that continuously monitors documentation quality, detects gaps, and creates issues for @claude to address documentation needs. This workflow complements the existing auto-documentation system by providing proactive documentation management.

Quick Start: For complete workflow information and developer guides, see the Documentation Workflows Hub.

Key Features

🤖 Automated Documentation Analysis

  • Gap Detection: Identifies missing documentation for critical components
  • Freshness Monitoring: Detects outdated documentation based on code changes
  • Stub File Management: Tracks and processes documentation placeholder files
  • Quality Scoring: Provides comprehensive quality metrics and reports

🎯 Smart Issue Creation

  • Automated Issue Generation: Creates GitHub issues when documentation problems are detected
  • Priority-based Classification: Labels issues by severity (critical, high, medium)
  • @claude Integration: Automatically assigns documentation tasks to Claude
  • Duplicate Prevention: Updates existing issues instead of creating duplicates

đź“… Continuous Monitoring

  • Daily Quality Reports: Comprehensive documentation health assessments
  • PR Impact Analysis: Checks if pull requests require documentation updates
  • Automatic Resolution Detection: Closes issues when documentation gaps are resolved
  • Trend Analysis: Tracks documentation quality improvements over time

System Architecture

GitHub Workflow File

Location: scripts/documentation-check.yml (to be moved to .github/workflows/)

The workflow includes multiple jobs:

  1. documentation-analysis - Main gap detection and issue creation
  2. stub-file-detection - Processes documentation placeholder files
  3. daily-documentation-review - Daily quality assessment
  4. close-completed-issues - Automatic issue resolution

Supporting Scripts

Core Analysis Scripts

  1. scripts/analyze-documentation-gaps.sh
    • Identifies missing documentation for critical components
    • Analyzes codebase to find undocumented features
    • Generates comprehensive gap reports with priority levels
  2. scripts/detect-stub-files.sh
    • Finds documentation stub files with markers like “STUB:”, “TODO:”, “PLACEHOLDER”
    • Categorizes stubs by priority and completion effort
    • Provides detailed analysis for each stub file
  3. scripts/check-documentation-freshness.sh
    • Compares documentation modification times with related code changes
    • Identifies potentially outdated documentation
    • Prioritizes updates based on critical path analysis

Issue Management Scripts

  1. scripts/create-documentation-issue.sh
    • Creates well-formatted GitHub issues for documentation tasks
    • Includes comprehensive task descriptions and checklists
    • Automatically assigns appropriate labels and priorities
  2. scripts/verify-documentation-issue-resolved.sh
    • Checks if documentation issues have been resolved
    • Compares current state with issue requirements
    • Enables automatic issue closure when tasks are complete

Quality Assessment Scripts

  1. scripts/generate-doc-quality-report.sh
    • Generates comprehensive daily documentation quality reports
    • Calculates quality scores and coverage metrics
    • Provides actionable recommendations and trend analysis
  2. scripts/check-pr-documentation-impact.sh
    • Analyzes pull request changes for documentation requirements
    • Identifies critical, high, and moderate impact changes
    • Provides specific recommendations for documentation updates
  3. scripts/process-stub-file.sh
    • Processes individual stub files to generate completion tasks
    • Analyzes stub content and finds related code files
    • Creates detailed completion checklists

Workflow Triggers

Automatic Triggers

  • Push Events: On pushes to dev, main, test, prod branches
  • Pull Requests: On PR creation/updates to dev and main
  • Daily Schedule: Every day at 2 AM UTC for quality reports
  • Manual Trigger: Workflow dispatch for on-demand analysis

Event-Specific Behavior

Push Events

  • Analyzes documentation gaps in the pushed code
  • Creates issues for newly detected gaps
  • Updates existing documentation issues with new findings

Pull Request Events

  • Checks if PR changes require documentation updates
  • Comments on PRs with documentation impact analysis
  • Provides specific recommendations for documentation changes

Daily Schedule

  • Generates comprehensive quality reports
  • Creates high-priority issues for critical documentation problems
  • Updates documentation metrics and badges

Issue Management

Issue Creation Logic

The workflow creates GitHub issues when:

  • Critical gaps detected: Missing documentation for core components
  • Stub files found: Documentation placeholders need completion
  • Outdated documentation: Code changes have made docs stale
  • Quality thresholds breached: Overall documentation quality is poor

Issue Labels

Issues are automatically labeled with:

  • documentation - All documentation-related issues
  • auto-documentation - Issues created by this workflow
  • critical / high-priority / medium-priority - Severity level
  • stub-files - Issues involving stub file completion
  • outdated - Issues involving documentation updates

Issue Assignment

All documentation issues are automatically assigned to @claude for resolution.

Issue Resolution

Issues are automatically closed when:

  • All critical documentation gaps are addressed
  • No stub files remain for critical issues
  • Documentation freshness checks pass
  • Quality scores meet resolution thresholds

Stub File System

Creating Stub Files

To indicate that new documentation is needed for a feature:

  1. Create a stub file in the appropriate docs/ subdirectory
  2. Use naming convention: FEATURE_NAME_STUB.md or TODO_FEATURE_NAME.md
  3. Include marker content:
# Feature Name Documentation

STUB: This documentation needs to be completed

## Requirements
- Document feature functionality
- Provide usage examples
- Include configuration options

TODO: Complete comprehensive documentation for this feature

Stub File Markers

The system recognizes these markers:

  • STUB: - Basic stub marker
  • TODO: - Task-oriented marker
  • PLACEHOLDER - Temporary content marker
  • COMING SOON - Future documentation marker
  • TBD - To be determined content
  • UNDER CONSTRUCTION - Work in progress marker

Stub Processing

The workflow automatically:

  1. Detects stub files in the docs/ directory
  2. Analyzes stub content and requirements
  3. Finds related code files for context
  4. Creates detailed completion tasks
  5. Prioritizes stubs based on location and content

Quality Metrics

Documentation Coverage

  • Calculation: (Total doc files / Total code files) Ă— 100
  • Target: >70% for good coverage, >90% for excellent

Quality Score (0-100)

  • Base Score: 100 points
  • Penalties:
    • Coverage <50%: -30 points
    • Coverage <70%: -15 points
    • Coverage <90%: -5 points
    • Critical issues: -15 points each
    • Moderate gaps: -5 points each
    • Stub files: -3 points each
    • Outdated docs: -2 points each
    • Structure violations: -5 points each

Quality Assessment Levels

  • 90-100: Excellent documentation
  • 75-89: Good documentation
  • 60-74: Fair documentation
  • 40-59: Poor documentation
  • 0-39: Critical issues requiring immediate attention

Configuration

Environment Variables

  • DOCS_BOT_NAME: Bot name for issue assignment (default: “claude”)
  • DOCS_LABEL: Primary documentation label (default: “documentation”)
  • AUTO_DOCS_LABEL: Automated issue label (default: “auto-documentation”)

GitHub Permissions Required

  • contents: read - Read repository files
  • issues: write - Create and update issues
  • pull-requests: write - Comment on pull requests

Dependencies

  • jq - JSON processing
  • tree - File structure visualization
  • gh CLI - GitHub operations
  • Standard Unix tools (find, grep, stat, etc.)

Documentation Standards Compliance

File Organization

The workflow enforces the documentation standards from CLAUDE.md:

  • Development docs → docs/development/
  • Feature docs → docs/features/
  • Testing docs → docs/testing/
  • Troubleshooting docs → docs/troubleshooting/

Naming Conventions

  • Uses CAPS_WITH_UNDERSCORES.md convention
  • Validates file placement in appropriate subdirectories
  • Checks for proper documentation index maintenance

Content Quality

  • Ensures documentation follows project standards
  • Validates completeness and currency
  • Provides specific improvement recommendations

Integration with Existing Systems

Auto-Documentation System

  • Complements the .txt upload system for AI assistant access
  • Uses same file analysis logic for consistency
  • Coordinates with CI/CD documentation generation

CI/CD Pipeline

  • Runs independently of build processes
  • Provides documentation status for deployment decisions
  • Integrates with existing quality gates

GitHub Issue Tracking

  • Creates actionable issues with clear requirements
  • Maintains issue lifecycle from creation to resolution
  • Provides detailed tracking and metrics

Usage Examples

Setting Up the Workflow

  1. Move the workflow file to the correct location: 
    mv scripts/documentation-check.yml .github/workflows/
  2. Ensure all scripts are executable: 
    chmod +x scripts/analyze-documentation-gaps.sh
chmod +x scripts/create-documentation-issue.sh
chmod +x scripts/detect-stub-files.sh
chmod +x scripts/check-documentation-freshness.sh
chmod +x scripts/process-stub-file.sh
chmod +x scripts/check-pr-documentation-impact.sh
chmod +x scripts/generate-doc-quality-report.sh
chmod +x scripts/verify-documentation-issue-resolved.sh
  3. Test the workflow locally: ```bash

    Test gap analysis

    ./scripts/analyze-documentation-gaps.sh

Test stub detection

./scripts/detect-stub-files.sh

Generate quality report

./scripts/generate-doc-quality-report.sh


### Creating Stub Files for New Features

When adding a new feature that needs documentation:

```bash
# Create stub file in appropriate location
cat > docs/features/NEW_FEATURE_STUB.md << EOF
# New Feature Documentation

STUB: This documentation needs to be completed for the new feature

## Requirements
- Document feature functionality  
- Provide usage examples
- Include integration guide
- Add troubleshooting section

TODO: Complete comprehensive documentation for the new feature implementation
EOF

Manual Workflow Trigger

Trigger documentation analysis manually:

gh workflow run documentation-check.yml --ref main -f force_check=true

Troubleshooting

Common Issues

  1. Script Permissions: Ensure all scripts are executable
  2. Missing Dependencies: Install required tools (jq, tree, gh)
  3. GitHub Token: Ensure workflow has proper GitHub token access
  4. File Paths: Verify script paths are correct for workflow execution

Debug Mode

Run scripts with debug output:

set -x  # Enable debug mode
./scripts/analyze-documentation-gaps.sh
set +x  # Disable debug mode

Workflow Logs

Check GitHub Actions logs for detailed execution information:

  • Go to repository → Actions → Documentation Check workflow
  • Review job logs for specific error messages
  • Check artifact downloads for analysis reports

Benefits

For Developers

  • Automated Documentation Maintenance: Reduces manual documentation overhead
  • Clear Documentation Requirements: Specific, actionable tasks for documentation
  • Quality Assurance: Continuous monitoring ensures documentation stays current
  • Integration with Development Workflow: Seamless integration with existing processes

For Documentation Quality

  • Proactive Gap Detection: Identifies documentation needs before they become problems
  • Comprehensive Coverage: Ensures all critical components are documented
  • Consistency Enforcement: Maintains documentation standards and organization
  • Trend Monitoring: Tracks documentation quality improvements over time

For AI Assistant Integration

  • Enhanced Context: Better documentation improves AI assistant responses
  • Automatic Updates: Documentation stays current with codebase changes
  • Structured Information: Well-organized documentation for easy AI access
  • Quality Assurance: Ensures AI assistants have accurate, up-to-date information

Future Enhancements

Potential Improvements

  1. Machine Learning Integration: Use ML to predict documentation needs
  2. Automated Content Generation: Generate draft documentation from code analysis
  3. Cross-Reference Validation: Verify documentation links and references
  4. Multi-Repository Support: Extend workflow to multiple repositories
  5. Integration with Documentation Tools: Connect with documentation platforms

Advanced Features

  1. Documentation Templates: Auto-generate documentation templates for new features
  2. Visual Documentation: Support for diagrams and visual documentation
  3. Version Tracking: Track documentation changes across versions
  4. Collaboration Features: Enhanced workflows for documentation collaboration
  5. Metrics Dashboard: Real-time documentation quality dashboard

Conclusion

The GitHub Documentation Workflow provides a comprehensive, automated solution for maintaining high-quality documentation. By continuously monitoring documentation health, creating actionable issues for @claude, and enforcing quality standards, this system ensures that documentation remains current, comprehensive, and valuable for both developers and AI assistants.

The workflow seamlessly integrates with existing development processes, providing proactive documentation management without disrupting normal development workflows. With its focus on automation, quality metrics, and integration with the broader documentation ecosystem, this system significantly improves documentation maintenance and quality assurance.

Core Documentation System

Development Integration

Quality and Testing

Component Documentation