# Outfitter Documentation

> Documentation structure and templates for READMEs, API docs, guides, and CLI references. Use when creating docs, writing READMEs, or structuring a docs/ directory.

- Skill: `outfitter-dev/outfitter-documentation` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add outfitter-dev/outfitter-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outfitter-dev/outfitter-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: outfitter-dev (https://skillmd.com/u/outfitter-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/outfitter-dev/outfitter-documentation

---


# Documentation Standards

Structure and templates for project documentation — the human-facing docs that help developers understand and use your project.

This skill covers _what_ to include and _where_ it goes. For _how_ to write it:

- Load the `outfitter-styleguide` skill for sentence rhythm, metaphors, structural moves
- Load the `outfitter-voice` skill for philosophical foundation (apply as review pass)

For agent-specific documentation (CLAUDE.md, AGENTS.md), load the `outfitter-agents-setup` skill.

## Documentation Hierarchy

Documentation is prioritized in this order:

1. **Types** — Self-documenting code through TypeScript types
2. **Inline comments** — TSDoc/JSDoc for non-obvious decisions
3. **`docs/`** — Broader architectural and reference material

All three levels matter. Types express intent through code, comments explain why, and docs provide context.

## Project Directory Structure

Standardized directory layout for documentation across repositories.

### Root-Level Files

| File              | Purpose                                             |
| ----------------- | --------------------------------------------------- |
| `README.md`       | Entry point for humans — quick start, links to docs |
| `CONTRIBUTING.md` | Contribution guidelines (if applicable)             |
| `CHANGELOG.md`    | Version history (auto-generated preferred)          |

### Standard Directories

```
project/
└── docs/
    ├── architecture/        # System design, ADRs
    ├── api/                 # API reference (if applicable)
    ├── cli/                 # CLI command reference
    ├── guides/              # How-to guides, tutorials
    └── development/         # Dev setup, workflows
```

### Directory Purpose

| Directory       | Content                                                            |
| --------------- | ------------------------------------------------------------------ |
| `architecture/` | System design docs, Architecture Decision Records (ADRs), diagrams |
| `api/`          | API reference, endpoint documentation, type definitions            |
| `cli/`          | Command reference, flags, usage examples, exit codes               |
| `guides/`       | How-to tutorials, walkthroughs, use-case guides                    |
| `development/`  | Contributing setup, local dev, testing, release process            |

### Source of Truth Principle

Each type of documentation should have one canonical location:

- **API reference** → Generated from code or `docs/api/`
- **CLI reference** → `docs/cli/` or generated from help text
- **Architecture decisions** → `docs/architecture/` or ADRs

Avoid duplicating content across locations. Link instead of copy.

## README Standards

READMEs are the entry point for new contributors. Keep them focused and scannable.

### Structure Template

See [templates/README.md](templates/README.md) for the full template.

### Length Guidelines

- **Target**: 150-250 lines
- **Maximum**: 400 lines (beyond this, extract to `docs/`)
- **Minimum**: 50 lines (needs at least: description, install, usage)
- **Flexible**: As long as needed for pain, value prop, quick starts, doc pointers

### What Belongs in README vs docs/

| README                       | `docs/`                      |
| ---------------------------- | ---------------------------- |
| Quick start (5-10 steps max) | Full tutorials               |
| Feature list (bullet points) | Feature deep-dives           |
| Installation options         | Configuration reference      |
| Links to detailed docs       | The detailed docs themselves |

### Leading Section Pattern

Choose based on project type:

- **Libraries/Tools**: Lead with "Quick Start" — users want to try it immediately
- **Frameworks/Platforms**: Lead with "Why X?" — users need to understand the value proposition
- **Internal Tools**: Lead with "Usage" — users already know why, they need how

### Stability Tier Labels

When documenting packages or components with different maturity levels, use these labels:

| Label      | Meaning                                | Guidance          |
| ---------- | -------------------------------------- | ----------------- |
| **Stable** | APIs locked, breaking changes rare     | Safe to depend on |
| **Active** | APIs evolving based on usage           | Watch for updates |
| **Early**  | APIs will change, not production-ready | Use with caution  |

Avoid metaphorical labels (Cold/Warm/Hot, etc.) — literal labels require no interpretation.

### Quick Start Best Practices

1. **Make it copy-paste runnable.** Use heredoc format when showing file creation:

   ```bash
   cat > example.ts << 'EOF'
   import { ok, err } from '@org/contracts';
   // ... code
   EOF
   bun run example.ts
   ```

2. **Show output, including errors.** Demonstrate both success and failure:

   ```
   $ my-tool search --query "test"
   Found: [ "result-1", "result-2" ]

   $ my-tool search
   Error [validation]: Query is required
   ```

   Showing error output proves your error handling works.

3. **End with a memorable closer.** After the output block, add a confident one-liner:

   ````markdown
   **Output:**

   ```
   Found: [ "result-1", "result-2" ]
   ```

   Done. You're building type-safe infrastructure.
   ````

4. **Use domain-relevant examples.** Avoid generic "Hello, World!" — use examples that demonstrate actual value.

## CLI Documentation

For projects with CLIs, document commands in `docs/cli/`.

### Command Reference Template

See [templates/COMMAND-REFERENCE.md](templates/COMMAND-REFERENCE.md) for the full template.

## Document Structure

Every technical document should follow the structure in [templates/DOCUMENT.md](templates/DOCUMENT.md).

### Heading Hierarchy

- **H1 (#)**: Document title only
- **H2 (##)**: Major sections
- **H3 (###)**: Subsections
- **H4 (####)**: Specific topics within subsections
- Avoid deeper nesting than H4

## Code Examples

### Requirements

- Include all necessary imports
- Show both definition and usage
- Add brief comments for complex logic
- Ensure examples are runnable
- Test examples before documenting

### Good Example

```typescript
interface UserConfig {
  timeout: number;
  retries: number;
}

function configureUser(options: UserConfig): void {
  // Validate timeout is positive
  if (options.timeout <= 0) {
    throw new Error("Timeout must be positive");
  }
  applyConfig(options);
}

// Usage
configureUser({ timeout: 5000, retries: 3 });
```

### Bad Example

```typescript
// Incomplete, lacks context
function configure(opts) {
  // ...
}
```

## API Documentation

### Function Documentation

````typescript
/**
 * Processes user data according to specified rules.
 *
 * @param userData - The raw user data to process
 * @param rules - Processing rules to apply
 * @returns Processed user data with applied transformations
 *
 * @example
 * ```typescript
 * const processed = processUser(
 *   { name: 'John', age: 30 },
 *   { uppercase: true }
 * );
 * // Returns: { name: 'JOHN', age: 30 }
 * ```
 *
 * @throws {ValidationError} When userData is invalid
 * @throws {RuleError} When rules cannot be applied
 */
function processUser(userData: UserData, rules: ProcessRules): ProcessedUser;
````

### Parameter Documentation

Always document:

- **Type**: Explicit TypeScript types
- **Purpose**: What the parameter controls
- **Constraints**: Valid ranges, formats, or values
- **Defaults**: If applicable
- **Examples**: For complex types

## Configuration Tables

```markdown
| Option    | Type      | Default | Description                     |
| --------- | --------- | ------- | ------------------------------- |
| `port`    | `number`  | `3000`  | Server port                     |
| `timeout` | `number`  | `30000` | Request timeout in milliseconds |
| `debug`   | `boolean` | `false` | Enable debug logging            |
```

## Maintenance

1. **Update with code**: Documentation changes must accompany code changes
2. **Review regularly**: Audit documentation quarterly for accuracy
3. **Remove outdated content**: Delete obsolete information rather than marking as deprecated
4. **Version appropriately**: Clearly document breaking changes and migration paths
5. **Test examples**: Verify all code examples work with current versions

## Review Checklist

Before finalizing documentation:

- [ ] All code examples are tested and working
- [ ] Technical terms are defined or linked
- [ ] Structure follows the standard template
- [ ] No outdated information remains
- [ ] Examples cover common use cases
- [ ] Error scenarios are documented
- [ ] API signatures are complete
- [ ] Cross-references are valid