gh-greyhaven-ai-claude-code-config-grey-haven-plugins-core/skills/documentation-alignment/reference/INDEX.md

Documentation Alignment Reference

Complete reference for verifying and maintaining code-documentation alignment.

Quick Navigation

Resource	Purpose	Best For
Alignment Verification Guide	Complete verification methodology	Understanding the process
Misalignment Patterns	Common issues and solutions	Troubleshooting
Automation Strategies	CI/CD integration	Production implementation

The 6-Phase Verification Process

Phase 1: Discovery

Goal: Find all documentation sources

Tasks:

• Locate inline documentation (docstrings, JSDoc, comments)
• Find markdown documentation (README, /docs)
• Identify API specs (OpenAPI, Swagger)
• Search for external documentation
• Map code structure and dependencies

Tools:

• File globbing for *.md, README*
• AST parsing for docstrings
• grep for comment patterns
• Documentation generators

Output: Complete inventory of code and docs

---

Phase 2: Extraction

Goal: Parse code and documentation into comparable format

Tasks:

• Extract function signatures (name, parameters, return types)
• Parse type information (TypeScript, Python type hints)
• Extract documentation strings
• Identify examples in docs
• Build structured data model

Tools:

• TypeScript Compiler API
• Python ast module
• Pydantic for Python
• JSDoc parser for JavaScript
• markdown-it for docs

Output: Structured representation of code vs docs

---

Phase 3: Analysis

Goal: Compare code against documentation

Comparisons:

1. Signature Alignment

   • Function name matches
   • Parameter count matches
   • Parameter names match
   • Parameter order correct

2. Type Alignment

   • Parameter types documented
   • Return types match
   • Generic types documented
   • Type constraints listed

3. Behavior Alignment

   • Documented behavior matches implementation
   • Side effects documented
   • Performance characteristics accurate
   • Async/sync behavior correct

4. Error Alignment

   • All thrown exceptions documented
   • Error conditions listed
   • Error messages match
   • Recovery strategies documented

5. Example Alignment

   • Code examples run successfully
   • Examples use current API
   • Examples demonstrate real use cases
   • Examples are copy-paste ready

Output: List of misalignments with severity

---

Phase 4: Classification

Goal: Prioritize issues for fixing

Severity Levels:

Critical (Fix Immediately):

• Breaking changes not documented
• Function signatures don't match
• Required parameters missing
• Examples that error
• Security implications

Important (Fix Soon):

• Public APIs undocumented
• Missing error documentation
• Type information incomplete
• Outdated examples
• Deprecated features still shown

Minor (Nice to Fix):

• Missing edge case docs
• Sparse descriptions
• No performance notes
• Internal functions documented as public

Alignment Scoring:

Score = (
  (SignatureMatch × 30) +
  (TypeMatch × 25) +
  (BehaviorMatch × 20) +
  (ErrorMatch × 15) +
  (ExampleMatch × 10)
) / 100

95-100: Perfect alignment
80-94: Good alignment
60-79: Poor alignment
0-59: Failing

Output: Prioritized list with alignment score

---

Phase 5: Fix Generation

Goal: Create fixes for misalignments

Fix Types:

1. Missing Documentation:

// Before (no docs)
function processData(data: Data[]): Result {
  return data.map(transform).filter(validate);
}

// After (generated docs)
/**
 * Process data items through transformation and validation pipeline.
 *
 * @param data - Array of data items to process
 * @returns Processed and validated results
 *
 * @example
 * ```typescript
 * const data = [{ id: 1, value: "test" }];
 * const results = processData(data);
 * // Returns validated, transformed data
 * ```
 */
function processData(data: Data[]): Result {
  return data.map(transform).filter(validate);
}

2. Outdated Documentation:

// Code updated but docs stale
function createUser(orgId: string, email: string, name: string) { ... }

// Old docs say:
// createUser(email, name)

// Generated fix:
/**
 * Create a new user in an organization.
 *
 * @param orgId - Organization ID (required as of v2.0)
 * @param email - User email address
 * @param name - User display name
 *
 * @migration v1.x → v2.0
 * organizationId is now the first required parameter
 */

3. Broken Examples:

// Example uses deprecated API
// Old: const user = await api.getUser(id);
// New: const user = await api.users.get(id);

// Generated replacement with migration note

Output: Ready-to-apply fixes

---

Phase 6: Validation

Goal: Ensure fixes resolve issues

Validation Steps:

1. Syntax Check: Generated docs are valid
2. Example Test: All examples run successfully
3. Type Check: Types match implementation
4. Consistency Check: Style matches project standards
5. Regression Check: Didn't break existing docs

Tools:

• TypeScript compiler for type checking
• Jest/Vitest for example testing
• ESLint/TSDoc for style
• Git diff for changes review

Output: Verified, production-ready documentation

---

Alignment Metrics

Code Coverage vs Doc Coverage

Code Coverage (tests):

• Measures % of code executed by tests
• Industry standard: 80%+

Doc Coverage (documentation):

• Measures % of public API documented
• Target: 95%+ for public APIs
• Target: 60%+ for internal APIs

Alignment Coverage:

• % of documented features that work as described
• Target: 98%+ alignment for production

Key Performance Indicators

Developer Productivity:

• Time to understand API: Target < 15 min
• Onboarding time: Target 1-2 days
• Support tickets from docs: Target < 5%

Documentation Quality:

• Alignment score: Target 95+
• Example success rate: Target 100%
• Doc freshness: Updated within 1 week of code changes

Maintenance Burden:

• Time to update docs: Target < 10% of dev time
• Automated coverage: Target 70%+
• Manual review needed: Target < 30%

---

Common Misalignment Patterns

Pattern 1: "Feature Creep"

Symptom: Function grows parameters, docs stay same Fix: Automated parameter detection Prevention: Pre-commit hooks

Pattern 2: "Refactor Drift"

Symptom: Function renamed, old name in docs Fix: AST-based find/replace Prevention: IDE refactoring tools

Pattern 3: "Example Rot"

Symptom: Examples use deprecated APIs Fix: Example test suite Prevention: CI testing all examples

Pattern 4: "Type Evolution"

Symptom: Types change, docs outdated Fix: Type extraction from code Prevention: Generated type docs

Pattern 5: "Behavior Divergence"

Symptom: Code does something different than docs say Fix: Behavioral testing + doc update Prevention: TDD with docs as specs

---

Tool Integration

TypeScript Projects

{
  "scripts": {
    "check-docs": "ts-node scripts/verify-docs-alignment.ts",
    "generate-docs": "typedoc --plugin typedoc-plugin-markdown",
    "test-examples": "vitest examples/**/*.test.ts"
  }
}

Python Projects

[tool.pydantic-docs]
alignment-threshold = 95
auto-fix = true

[tool.pytest.ini_options]
testpaths = ["docs/examples"]
doctest_optionflags = "NORMALIZE_WHITESPACE"

CI/CD Integration

# .github/workflows/docs.yml
- name: Check Documentation Alignment
  run: npm run check-docs
  # Fails if score < 85

- name: Test Documentation Examples
  run: npm run test-examples
  # Ensures all examples work

---

Best Practices

1. Single Source of Truth

Principle: Code is the source of truth for signatures Implementation:

• Generate docs from code when possible
• Extract types directly from implementation
• Auto-generate parameter lists

2. Test Documentation

Principle: Documentation should be testable Implementation:

• Run code examples in CI
• Use doctest for Python
• TypeScript examples as tests

3. Version Documentation

Principle: Docs should match code version Implementation:

• Tag docs with version numbers
• Maintain changelog for API changes
• Show migration guides

4. Automate Where Possible

Principle: Reduce manual documentation burden Implementation:

• Generate from types (TypeDoc, Sphinx autodoc)
• Extract from comments (JSDoc → markdown)
• Test examples automatically

5. Make Breaking Changes Obvious

Principle: API changes should be impossible to miss Implementation:

• BREAKING CHANGE tags
• Migration guides
• Deprecation warnings
• Version badges

---

Quick Start:

1. Read Alignment Verification Guide
2. Identify misalignments using Patterns
3. Automate with Strategies
4. Use Templates for common scenarios

Success Metrics:

• 95%+ alignment score
• < 5% documentation-related bugs
• 70%+ automated coverage
• 1-day onboarding time