Docs Specialist

Documentation Specialist Skill

Overview

This skill provides specialized expertise in technical documentation: generating docs from code, detecting drift between docs and implementation, validating quality, and applying consistent templates.

Documentation Reference

CRITICAL: Before working on documentation tasks, consult:

• docs-specialist/skills/docs-specialist/references/documentation-patterns.md

Expertise Areas

1. Code-to-Docs Generation

Analyze source code and generate documentation automatically:

Process: 1. Scan code files (routes, models, components, services) 2. Extract structure (classes, functions, signatures) 3. Parse existing comments (JSDoc, docstrings) 4. Apply appropriate template 5. Generate formatted documentation

2. Docs-to-Code Sync Detection

Compare documentation against code to find discrepancies:

3. Documentation Validation

Check quality, accuracy, and completeness:

• Link integrity (internal and external)
• Code example accuracy
• Structure and formatting
• Completeness by doc type
• Technical accuracy against code

4. Template System

Apply consistent templates for different documentation types:

Commands

See each command's file for full syntax and options.

Working Principles

Accuracy First

• Always verify against source code
• Test code examples before documenting
• Flag assumptions or uncertainties
• Update immediately when code changes

Code Analysis Approach

When analyzing code for documentation: 1. Parse file structure (AST when possible) 2. Extract public interfaces first 3. Include type information 4. Find usage examples in tests 5. Respect existing documentation comments

Sync Detection Approach

When comparing docs to code: 1. Build inventory of documented items 2. Build inventory of code items 3. Match by name/path/signature 4. Categorize matches (exact, partial, missing) 5. Detail differences for partial matches

Documentation Standards

File Organization

docs/
├── README.md               # Documentation hub
├── api/                    # API reference
├── guides/                 # User guides
├── architecture/           # System design
└── development/            # Developer docs

Markdown Conventions

• ATX-style headers (#)
• Code blocks with language specification
• Relative links for internal references
• One sentence per line (for diffs)

Code Examples

• Complete, runnable examples
• Include imports/setup
• Show expected output
• Highlight key lines

Tool-Specific Files

Keep these in their original locations (DO NOT move to /docs):

• CLAUDE.md - Root directory
• .claude/commands/*.md - Command definitions
• .claude/agents/*.md - Agent definitions
• .cursorrules - Cursor AI configuration

Version Control

• Use conventional commits: docs: description
• Link doc commits to code commits when related
• Group related documentation updates

Quality Checklist

Before considering documentation complete:

• [ ] All code examples tested and working
• [ ] Technical accuracy confirmed against code
• [ ] Links valid and correct
• [ ] Formatting consistent
• [ ] Procedures complete and actionable
• [ ] Sync check passes
• [ ] Validation score above threshold

Common Workflows

"I wrote new code, need docs"

/docs-specialist:docs generate <path>

"I changed code, update docs"

/docs-specialist:sync check
/docs-specialist:sync fix

"Audit documentation quality"

/docs-specialist:docs validate
/docs-specialist:sync check

"Set up docs for new project"

/docs-specialist:init
/docs-specialist:docs generate all

"Pre-release check"

/docs-specialist:doctor --check
/docs-specialist:sync check
/docs-specialist:docs validate

Success Metrics

Excellent documentation is:

• Accurate - Reflects current code reality
• Complete - Covers all necessary topics
• In Sync - No drift from implementation
• Clear - Easy to understand
• Maintainable - Easy to update
• Actionable - Readers can accomplish goals

Documentation Patterns Reference

Documentation Types

File Organization by Project Type

Laravel Projects

docs/
├── README.md
├── api/
│   ├── authentication.md
│   ├── users.md
│   └── [resource].md
├── models/
│   ├── user.md
│   └── [model].md
├── guides/
│   ├── installation.md
│   ├── deployment.md
│   └── [topic].md
├── architecture/
│   ├── overview.md
│   └── decisions/
│       └── [ADR-001-title].md
└── development/
    ├── contributing.md
    ├── testing.md
    └── coding-standards.md

Key files to document:

• Routes (routes/api.php, routes/web.php) → docs/api/
• Models (app/Models/) → docs/models/
• Config files (config/) → docs/configuration.md
• Migrations → Referenced in model docs

Node.js Projects

docs/
├── README.md
├── api/
│   ├── endpoints.md
│   └── [resource].md
├── guides/
│   ├── getting-started.md
│   └── [topic].md
├── architecture/
│   └── overview.md
└── development/
    ├── contributing.md
    └── testing.md

Key files to document:

• Route handlers → docs/api/
• Middleware → docs/architecture/
• Package exports → docs/api/
• Environment variables → docs/configuration.md

React/Vue/Frontend Projects

docs/
├── README.md
├── components/
│   ├── index.md
│   └── [ComponentName].md
├── guides/
│   ├── getting-started.md
│   ├── theming.md
│   └── [topic].md
├── architecture/
│   ├── state-management.md
│   └── routing.md
└── development/
    ├── contributing.md
    └── testing.md

Key files to document:

• Components (src/components/) → docs/components/
• Hooks/composables → docs/api/
• Store/state → docs/architecture/
• Theme/config → docs/guides/theming.md

Markdown Best Practices

Headers

• Use ATX-style (#) exclusively
• Never skip levels (h1 → h3 without h2)
• One h1 per file (the document title)
• Use sentence case for headers

Code Blocks

• Always specify language: `php , `bash , `json
• Include complete, runnable examples
• Show imports and setup needed
• Add comments for non-obvious lines
• Show expected output when helpful

Links

• Use relative paths for internal links: [Models](../models/user.md)
• Use reference-style links for repeated URLs
• Check links during validation

Lists

• Use - for unordered lists
• Use 1. for ordered lists (auto-numbered)
• Indent nested items with 2 or 4 spaces consistently

Tables

• Use for structured comparisons or reference data
• Align columns for readability in source
• Keep cell content concise

Line Length

• One sentence per line (improves git diffs)
• Exception: tables and code blocks

Template Selection Guide

Drift Detection Patterns

What to Compare for Each Artifact Type

API Endpoints

Models / Entities

Components (React / Vue / Livewire)

Configuration

Common Drift Causes

1. Code refactored, docs not updated - Most frequent. Catch with regular sync checks. 2. Feature removed but docs remain - Results in "Not Implemented" status. 3. New feature added without docs - Results in "Undocumented" status. 4. Parameter renamed/retyped - Results in "Partial" match with parameter mismatch. 5. Response format changed - Results in "Partial" match with schema difference.