ComputerConnection/skills/docs

Documentation Generator: $ARGUMENTS

Find what's missing. Write what's needed.

---

Scope: External-Facing Documentation

This skill produces documentation for external audiences:

• Users of your library/tool
• API consumers
• Open source contributors
• Future maintainers unfamiliar with your team

For internal team onboarding (new developers joining your team), use /onboard instead.

| Use /docs for | Use /onboard for | |---------------|------------------| | README.md | ONBOARDING.md | | API reference | "How we work" guides | | Public setup guide | Internal dev environment | | Architecture overview | Team conventions & gotchas | | CONTRIBUTING.md | "Who to ask" directory |

---

Philosophy

• Documentation is a product - Treat it like code: versioned, reviewed, maintained
• Write for the reader - User? API consumer? Contributor?
• Show, don't just tell - Examples > explanations
• Keep it fresh - Stale docs are worse than no docs
• Start from code - The truth is in the source

---

Phase 1: Documentation Audit

Scan for Existing Docs

# Find all documentation
find . -name "README*" -o -name "*.md" -o -name "CHANGELOG*" -o -name "CONTRIBUTING*" 2>/dev/null

# Check for doc generators
ls -la docs/ 2>/dev/null
cat package.json | grep -i "doc"

Documentation Inventory

┌─────────────────────────────────────────────────────────────┐
│  DOCUMENTATION AUDIT: [Project]                             │
├─────────────────────────────────────────────────────────────┤
│  Found                          │ Missing                   │
│  ───────────────────────────────┼───────────────────────────│
│  [ ] README.md                  │ [x] README.md             │
│  [ ] API docs                   │ [x] API docs              │
│  [ ] Architecture              │ [x] Architecture           │
│  [ ] Setup guide                │ [x] Setup guide           │
│  [ ] Contributing guide         │ [x] Contributing          │
│  [ ] Changelog                  │ [x] Changelog             │
│  [ ] Code comments              │ [x] Code comments         │
└─────────────────────────────────────────────────────────────┘

Gap Analysis

| Doc Type | Status | Quality | Priority | |----------|--------|---------|----------| | README | Missing | - | P0 | | API | Exists | Outdated | P1 | | Setup | Partial | Incomplete | P1 | | Architecture | Missing | - | P2 |

---

Phase 2: README Generation

README Structure

# [Project Name]

> [One-line description - what this does]

[Optional badge row: build status, version, license]

## What This Does

[2-3 sentences explaining the core value proposition]

## Quick Start

\`\`\`bash
# Installation
[single command to install]

# Run it
[single command to run]
\`\`\`

## Features

- **[Feature 1]**: [brief description]
- **[Feature 2]**: [brief description]
- **[Feature 3]**: [brief description]

## Usage

### Basic Example
\`\`\`[language]
[minimal working example]
\`\`\`

### [Common Use Case]
\`\`\`[language]
[example for this use case]
\`\`\`

## Configuration

| Option | Default | Description |
|--------|---------|-------------|
| `option1` | `value` | What it does |
| `option2` | `value` | What it does |

## Project Structure

\`\`\`
project/
├── src/           # Source code
│   ├── main.ts    # Entry point
│   └── lib/       # Core library
├── tests/         # Test files
└── docs/          # Documentation
\`\`\`

## Development

\`\`\`bash
# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build
\`\`\`

## Contributing

[Brief contribution guidelines or link to CONTRIBUTING.md]

## License

[License type] - see [LICENSE](./LICENSE)

README Quality Checklist

• [ ] Can a new person understand what this is in 30 seconds?
• [ ] Can they get it running in under 5 minutes?
• [ ] Are the most common use cases documented?
• [ ] Is the project structure explained?
• [ ] Is the development workflow clear?

---

Phase 3: API Documentation

Endpoint Documentation Template

## [Resource Name]

### [METHOD] /api/[path]

[One sentence description]

**Authentication**: Required / Optional / None

**Request**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `param1` | string | Yes | Description |
| `param2` | number | No | Description (default: 0) |

**Request Body**
\`\`\`json
{
  "field1": "value",
  "field2": 123
}
\`\`\`

**Response**

\`\`\`json
{
  "id": "abc123",
  "status": "success",
  "data": { ... }
}
\`\`\`

**Errors**

| Code | Message | Cause |
|------|---------|-------|
| 400 | Invalid input | Field validation failed |
| 401 | Unauthorized | Missing or invalid token |
| 404 | Not found | Resource doesn't exist |

**Example**

\`\`\`bash
curl -X POST https://api.example.com/api/resource \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field1": "value"}'
\`\`\`

API Doc Extraction

# Find all routes/endpoints
grep -r "router\." --include="*.ts" --include="*.js" src/
grep -r "@Get\|@Post\|@Put\|@Delete" --include="*.ts" src/
grep -r "app\.get\|app\.post" --include="*.ts" --include="*.js" src/

---

Phase 4: Architecture Documentation

Architecture Doc Template

# Architecture: [Project Name]

## Overview

[2-3 paragraphs describing the system at a high level]

## System Diagram

\`\`\`
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────►│     API     │────►│  Database   │
│   (React)   │     │   (Node)    │     │  (Postgres) │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    ┌──────▼──────┐
                    │   Queue     │
                    │   (Redis)   │
                    └─────────────┘
\`\`\`

## Components

### [Component Name]
**Location**: `src/components/[name]`
**Responsibility**: [what it does]
**Dependencies**: [what it uses]
**Dependents**: [what uses it]

### [Component Name]
...

## Data Flow

### [Flow Name]
1. User triggers [action]
2. [Component A] handles request
3. [Component B] processes data
4. [Component C] persists result
5. Response returned to user

## Key Decisions

| Decision | Rationale | Alternatives Considered |
|----------|-----------|------------------------|
| [Decision 1] | [Why] | [What else we considered] |

## Technology Stack

| Layer | Technology | Purpose |
|-------|------------|---------|
| Frontend | React + TypeScript | UI |
| Backend | Node.js + Express | API |
| Database | PostgreSQL | Persistence |
| Cache | Redis | Sessions, queues |

## Directory Structure

\`\`\`
src/
├── api/          # API routes and controllers
├── services/     # Business logic
├── models/       # Data models
├── utils/        # Shared utilities
└── config/       # Configuration
\`\`\`

## Patterns Used

- **[Pattern 1]**: [Where and why]
- **[Pattern 2]**: [Where and why]

## Known Limitations

- [Limitation 1]: [Impact and potential solution]
- [Limitation 2]: [Impact and potential solution]

---

Phase 5: Setup Guide

Setup Guide Template

# Setup Guide

## Prerequisites

- [ ] [Tool 1] (version X.X+) - [why needed]
- [ ] [Tool 2] (version X.X+) - [why needed]

### Installing Prerequisites

**macOS**
\`\`\`bash
brew install [tools]
\`\`\`

**Linux (Ubuntu/Debian)**
\`\`\`bash
apt-get install [tools]
\`\`\`

**Windows**
\`\`\`bash
[instructions]
\`\`\`

## Installation

### 1. Clone the Repository
\`\`\`bash
git clone [repo-url]
cd [project-name]
\`\`\`

### 2. Install Dependencies
\`\`\`bash
npm install
\`\`\`

### 3. Configure Environment
\`\`\`bash
cp .env.example .env
# Edit .env with your values
\`\`\`

**Required Environment Variables**

| Variable | Description | Example |
|----------|-------------|---------|
| `DATABASE_URL` | Database connection | `postgres://localhost/db` |
| `API_KEY` | External service key | `abc123...` |

### 4. Initialize Database
\`\`\`bash
npm run db:migrate
npm run db:seed  # Optional: seed test data
\`\`\`

### 5. Verify Installation
\`\`\`bash
npm test
\`\`\`

## Running the Application

### Development Mode
\`\`\`bash
npm run dev
\`\`\`
Open http://localhost:3000

### Production Mode
\`\`\`bash
npm run build
npm start
\`\`\`

## Common Issues

### [Issue: Description]
**Symptom**: [What you see]
**Cause**: [Why it happens]
**Fix**: [How to resolve]

### [Issue: Description]
...

## Next Steps

- [ ] Read the [Architecture Docs](./ARCHITECTURE.md)
- [ ] Check the [API Documentation](./API.md)
- [ ] Review the [Contributing Guide](./CONTRIBUTING.md)

---

Phase 6: Code Documentation

When to Add Comments

┌─────────────────────────────────────────────────────────────┐
│  DO comment:                                                │
│  • Why (not what) - non-obvious decisions                   │
│  • Public APIs - function signatures                        │
│  • Complex algorithms - high-level explanation              │
│  • Workarounds - link to issue/reason                       │
│  • Business rules - cite the source                         │
├─────────────────────────────────────────────────────────────┤
│  DON'T comment:                                             │
│  • What the code does (code should be clear)                │
│  • Obvious things (// increment counter)                    │
│  • Change history (use git)                                 │
│  • Commented-out code (delete it)                           │
└─────────────────────────────────────────────────────────────┘

JSDoc/TSDoc Template

/**
 * [Brief description of what this does]
 *
 * [Longer description if needed - when to use, important behavior]
 *
 * @param paramName - Description of parameter
 * @param options - Configuration options
 * @param options.timeout - Request timeout in ms (default: 5000)
 * @returns Description of return value
 * @throws {ErrorType} When [condition]
 *
 * @example
 * ```typescript
 * const result = await doThing('input', { timeout: 3000 });
 * console.log(result.data);
 * ```
 */
async function doThing(paramName: string, options?: Options): Promise<Result> {
  // Implementation
}

Identifying Undocumented Code

# Find exported functions without JSDoc
grep -rn "^export function\|^export async function\|^export const" --include="*.ts" src/ | head -20

# Find classes without documentation
grep -rn "^export class\|^class " --include="*.ts" src/ | head -20

---

Phase 7: Documentation Generation

Auto-Generation from Code

# TypeScript: Generate API docs
npx typedoc --out docs/api src/

# OpenAPI/Swagger from code
# (if using decorators like tsoa, nestjs-swagger)
npm run generate:docs

# From existing OpenAPI spec
npx redoc-cli bundle openapi.yaml -o docs/api.html

Keep Docs in Sync

## Documentation Maintenance

### Auto-generated (don't edit manually)
- `docs/api/` - Generated from TSDoc comments
- `docs/openapi.json` - Generated from route decorators

### Manual maintenance
- `README.md` - Update when features change
- `ARCHITECTURE.md` - Update when structure changes
- `SETUP.md` - Update when dependencies change

### Review triggers
- [ ] New feature added → Update README features
- [ ] API changed → Regenerate API docs
- [ ] New dependency → Update setup guide
- [ ] Architecture change → Update architecture doc

---

Phase 8: Documentation Output

Priority Matrix

| Doc | Audience | Priority | Effort | |-----|----------|----------|--------| | README | Everyone | P0 | Low | | Setup Guide | New devs | P0 | Medium | | API Docs | API consumers | P1 | Medium | | Architecture | Team | P2 | High | | Contributing | Contributors | P2 | Low |

Output Files

docs/
├── README.md           # Project overview
├── SETUP.md            # Getting started
├── ARCHITECTURE.md     # System design
├── API.md              # API reference
├── CONTRIBUTING.md     # How to contribute
└── CHANGELOG.md        # Version history

Documentation Health Score

┌─────────────────────────────────────────────────────────────┐
│  DOCUMENTATION HEALTH: [Project]                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  README            [████████░░] 80%                         │
│  API Docs          [████░░░░░░] 40%                         │
│  Setup Guide       [██████████] 100%                        │
│  Architecture      [░░░░░░░░░░] 0%                          │
│  Code Comments     [██████░░░░] 60%                         │
│                                                             │
│  Overall Score: 56% - Needs Work                            │
│                                                             │
│  Top Priority: Create ARCHITECTURE.md                       │
└─────────────────────────────────────────────────────────────┘

---

Keeping Docs in Sync

Automation Options

# Pre-commit hook to check doc freshness
# .husky/pre-commit or .git/hooks/pre-commit

# Warn if API changed but docs didn't
if git diff --cached --name-only | grep -q "src/api/"; then
  if ! git diff --cached --name-only | grep -q "docs/api\|API.md"; then
    echo "Warning: API files changed but docs not updated"
  fi
fi

CI Checks

# GitHub Actions example
- name: Check docs freshness
  run: |
    # Regenerate API docs
    npm run docs:generate
    # Fail if generated docs differ from committed
    git diff --exit-code docs/

Documentation Review Triggers

Add to PR template:

## Documentation
- [ ] README updated (if user-facing changes)
- [ ] API docs updated (if endpoints changed)
- [ ] CHANGELOG updated

---

Anti-Patterns

• "The code documents itself" (it doesn't, for the non-obvious)
• Wall of text READMEs (nobody reads them)
• No examples (show, don't tell)
• Outdated docs (worse than no docs)
• Documentation as afterthought (do it as you build)
• Over-documentation (document decisions, not obvious code)
• Duplicating onboarding content (use /onboard for internal team docs)

---

Output

1. Documentation audit with gap analysis
2. README.md (if missing/incomplete)
3. SETUP.md (if missing/incomplete)
4. API.md or endpoint docs (if applicable)
5. ARCHITECTURE.md (if missing/incomplete)
6. Inline documentation recommendations
7. Documentation health score
8. Maintenance plan