Technical Documentation Generator

Overview

Generate comprehensive technical documentation by analyzing the actual codebase. Produces API references, architecture overviews, getting started guides, and component documentation with real examples extracted from project code, not invented ones.

Announce at start: "I'm using the tech-docs-generator skill to create documentation."

Phase 1: Codebase Analysis

Scan the codebase to identify what needs documenting. Deploy parallel subagents via the Agent tool (up to 500, with subagent_type="Explore") to analyze:

STOP after analysis — present a summary of what was found and ask which documentation types are needed.

Phase 2: Documentation Type Selection

Ask the user which type(s) they need if not specified. If multiple types are requested, dispatch parallel subagents via the Agent tool — one per doc type.

Phase 3: Generate Documentation

Dispatch doc-generator agent with:

• File analysis results from Phase 1
• Documentation type selected in Phase 2
• Existing documentation (to update, not replace)
• Project context from memory files

STOP after generation — present each section for review before saving.

Documentation Format Standards

API Reference format:

## `functionName(param1, param2)`

Description of what this function does.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | `string` | Yes | What it does |
| param2 | `Options` | No | Configuration options |

**Returns:** `Promise<Result>`

**Example:**
```typescript
const result = await functionName('value', { option: true });

Throws: ValidationError if param1 is empty

**Architecture Overview format:**

```markdown
## System Architecture

### Overview
[High-level description with ASCII diagram]

### Components
| Component | Responsibility | Key Files |
|-----------|---------------|-----------|

### Data Flow
[How data moves through the system — request lifecycle]

### Key Decisions
| Decision | Rationale | Alternatives Considered |
|----------|-----------|------------------------|

Getting Started format:

## Prerequisites
[Required tools, versions, accounts]

## Installation
[Step-by-step with copy-pasteable commands]

## Configuration
[Required env vars and config]

## First Run
[How to start the app and verify it works]

## Next Steps
[Links to deeper documentation]

Phase 4: Review and Save

Present documentation section by section:

1. Ask after each section: "Does this accurately describe the code?"
2. Cross-reference with actual code to verify accuracy
3. Include real examples from the codebase — never invented ones
4. After approval, save to docs/ directory
5. Commit with message: docs(<scope>): add/update <doc-type>

Accuracy Verification Checklist

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

• Do NOT generate documentation without first analyzing the actual code
• Do NOT invent examples — every code snippet must come from or be verified against the codebase
• Do NOT document private/internal APIs unless explicitly requested
• Do NOT skip the review phase — present each section for user verification
• Do NOT duplicate information already covered in other docs — reference instead

Integration Points

Verification Gate

Before claiming documentation is complete:

1. VERIFY all public APIs are documented with correct signatures
2. VERIFY code examples actually work (not invented)
3. VERIFY cross-references link to existing content
4. VERIFY documentation matches current code state
5. VERIFY the user has approved each section
6. RUN any documented commands to confirm they work

Concrete Example: API Reference Entry

Given this source code:

export async function createUser(data: CreateUserInput): Promise<User> {
  // validates, hashes password, inserts into DB
}

Generate this documentation:

## `createUser(data)`

Create a new user account with the provided details.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| data | `CreateUserInput` | Yes | User registration data |

**`CreateUserInput` shape:**
| Field | Type | Required | Constraints |
|-------|------|----------|-------------|
| email | `string` | Yes | Valid email format |
| password | `string` | Yes | Minimum 8 characters |
| name | `string` | Yes | 1-100 characters |

**Returns:** `Promise<User>` — the created user object (password excluded)

**Throws:**
- `ValidationError` — if input fails validation
- `ConflictError` — if email already exists

Skill Type

Flexible — Adapt documentation depth and format to project needs while preserving the analyze-first principle and accuracy verification.