Documentation Engineer

# Documentation Engineer

> A Claude Code skill for creating clear, comprehensive documentation.

## Installation

This skill is part of the [agent-playbook](../../README.md) collection.

## Usage

```
You: Write documentation for this API
You: Create a README
You: Document this code
```

## Documentation Types

| Type | Description |
|------|-------------|
| **README** | Project overview and quick start |
| **API Docs** | Endpoint/function documentation |
| **Code Comments** | Inline explanations |
| **Architecture** | System design documentation |

## Scripts

Generate documentation structure:
```bash
python scripts/generate_docs.py
```

Validate documentation:
```bash
python scripts/validate_docs.py
```

## Resources

- [Google Developer Documentation Style Guide](https://developers.google.com/tech-writing/one)
- [Diátaxis Framework](https://diataxis.fr/)


# API Documentation Template

## Endpoint: /resource

**Method:** GET | POST | PUT | DELETE

**Description:** What the endpoint does.

### Parameters
- `id` (string, required) - Resource identifier

### Response
```json
{
  "data": {}
}
```

### Errors
- `400` Bad Request
- `401` Unauthorized
- `404` Not Found


# README Template

## Overview
Describe what the project does and why it exists.

## Quick Start
1. Install dependencies
2. Configure environment
3. Run the main command

## Installation
- Requirements
- Setup steps

## Usage
Provide common usage examples.

## Configuration
List environment variables and configuration options.

## Development
How to lint, test, and build locally.

## Contributing
Explain how to propose changes.


# Documentation Style Guide

## Headings
- Use sentence case
- Keep headings short and specific

## Code Blocks
- Always specify a language
- Keep examples minimal and runnable

## Links
- Use relative links for internal docs
- Prefer stable URLs for external references


#!/usr/bin/env python3
# Template generator for documentation scaffold.

from pathlib import Path
import argparse
import textwrap


def write_output(path: Path, content: str, force: bool) -> bool:
    if path.exists() and not force:
        print(f"{path} already exists (use --force to overwrite)")
        return False
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(content, encoding="utf-8")
    return True


def main() -> int:
    parser = argparse.ArgumentParser(description="Generate documentation scaffold.")
    parser.add_argument("--output", default="docs/README.md", help="Output file path")
    parser.add_argument("--name", default="example", help="Product or service name")
    parser.add_argument("--owner", default="team", help="Owning team")
    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
    args = parser.parse_args()

    content = textwrap.dedent(
        f"""\
        # Documentation

        ## Overview
        Describe {args.name} and its purpose.

        ## Ownership
        - Owner: {args.owner}
        - Support channel: TBD

        ## Quickstart
        1. Install dependencies
        2. Configure environment
        3. Run the service

        ## Configuration
        - Required environment variables
        - Feature flags

        ## Usage
        Examples for {args.name}.

        ## API Reference
        - Endpoints or SDK methods

        ## Troubleshooting
        - Common errors and fixes

        ## Changelog
        - Recent updates
        """
    ).strip() + "\n"

    output = Path(args.output)
    if not write_output(output, content, args.force):
        return 1
    print(f"Wrote {output}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


#!/usr/bin/env python3
# Template validator for documentation scaffold.

from pathlib import Path
import argparse

DEFAULT_REQUIRED = [
    "## Overview",
    "## Ownership",
    "## Quickstart",
    "## Configuration",
    "## Usage",
    "## Troubleshooting",
]


def main() -> int:
    parser = argparse.ArgumentPa