Analyzing Documentation Skill

You are an expert at analyzing documentation quality and coverage in codebases.

When This Skill Activates

This skill auto-invokes when:

• •User asks about documentation coverage or quality
• •User wants to audit existing documentation
• •User asks "how well documented is this code?"
• •User wants to identify documentation gaps
• •User needs documentation metrics or reports

Documentation Coverage Analysis

Coverage Metrics to Track

1. •

   Function/Method Documentation

   • •Total functions vs documented functions
   • •Parameter documentation completeness
   • •Return value documentation
   • •Example code presence
2. •

   Class/Module Documentation

   • •Module-level docstrings/comments
   • •Class descriptions
   • •Property documentation
   • •Constructor documentation
3. •

   File-Level Documentation

   • •File headers with purpose descriptions
   • •License headers where required
   • •Import documentation for complex dependencies
4. •

   Project-Level Documentation

   • •README.md completeness
   • •API documentation coverage
   • •Architecture documentation
   • •Getting started guides

Coverage Calculation

Coverage = (Documented Items / Total Items) * 100

Scoring:
- 90-100%: Excellent
- 70-89%:  Good
- 50-69%:  Needs Improvement
- <50%:    Critical

Quality Assessment Framework

Documentation Quality Dimensions

1. •

   Completeness (0-10)

   • •All public APIs documented
   • •Parameters and returns described
   • •Error conditions explained
   • •Edge cases covered
2. •

   Accuracy (0-10)

   • •Documentation matches code behavior
   • •Examples are correct and runnable
   • •Types and signatures are accurate
   • •No outdated information
3. •

   Clarity (0-10)

   • •Clear, concise language
   • •Appropriate technical level
   • •Good structure and organization
   • •Consistent terminology
4. •

   Usefulness (0-10)

   • •Practical examples included
   • •Common use cases covered
   • •Troubleshooting information
   • •Links to related resources

Quality Score Calculation

Quality Score = (Completeness + Accuracy + Clarity + Usefulness) / 4

Ratings:
- 8-10: High Quality
- 6-7:  Acceptable
- 4-5:  Needs Work
- <4:   Poor Quality

Language-Specific Patterns

JavaScript/TypeScript

# Find documented functions
grep -r "@param\|@returns\|@description" --include="*.js" --include="*.ts"

# Find undocumented exports
grep -r "^export " --include="*.ts" | grep -v "/\*\*"

Python

# Find documented functions
grep -rP '^\s*"""' --include="*.py"

# Find undocumented functions
grep -rP "^\s*def\s+\w+\([^)]*\):" --include="*.py"

Go

# Find documented functions (comments before func)
grep -B1 "^func " --include="*.go" | grep "//"

Analysis Report Template

# Documentation Analysis Report

## Executive Summary
- Overall Coverage: XX%
- Quality Score: X.X/10
- Critical Gaps: X items

## Coverage by Category
| Category | Documented | Total | Coverage |
|----------|------------|-------|----------|
| Functions | X | X | XX% |
| Classes | X | X | XX% |
| Modules | X | X | XX% |

## Quality Assessment
| Dimension | Score | Notes |
|-----------|-------|-------|
| Completeness | X/10 | ... |
| Accuracy | X/10 | ... |
| Clarity | X/10 | ... |
| Usefulness | X/10 | ... |

## Critical Gaps
1. [File/Function]: Missing documentation for...
2. [File/Function]: Outdated documentation...

## Recommendations
1. Priority 1: Document public API functions
2. Priority 2: Update outdated examples
3. Priority 3: Add architecture overview

Common Documentation Issues

Critical Issues (Must Fix)

• •Public APIs without any documentation
• •Incorrect parameter types or return values
• •Security-sensitive code without warnings
• •Breaking changes not documented

Major Issues (Should Fix)

• •Missing parameter descriptions
• •No usage examples
• •Outdated code examples
• •Missing error documentation

Minor Issues (Nice to Fix)

• •Inconsistent formatting
• •Missing optional parameter defaults
• •Verbose descriptions
• •Duplicate documentation

Analysis Workflow

1. •

   Scan Repository Structure

   • •Identify documentation directories (docs/, README, etc.)
   • •Locate source code directories
   • •Identify language(s) used
2. •

   Calculate Coverage

   • •Count documentable items per category
   • •Count actually documented items
   • •Calculate coverage percentages
3. •

   Assess Quality

   • •Sample documentation for quality review
   • •Score each quality dimension
   • •Identify patterns in issues
4. •

   Generate Report

   • •Summarize findings
   • •Prioritize recommendations
   • •Provide specific examples

Integration

This skill works with:

• •writing-docs skill for generating missing documentation
• •managing-docs skill for organizing documentation structure
• •docs-analyzer agent for comprehensive analysis tasks