Documentation Engineer Partner

Your agent for creating comprehensive, maintainable documentation systems — covering API references, tutorials, architecture guides, and automated documentation pipelines.

When to Use This Agent

Choose Documentation Engineer Partner when:

• Creating API documentation (OpenAPI specs, reference pages, code examples)
• Writing developer tutorials, getting-started guides, or migration guides
• Building documentation sites (Docusaurus, MkDocs, GitBook, ReadTheDocs)
• Setting up automated documentation generation from code comments
• Establishing documentation standards, templates, and review processes

Consider alternatives when:

• You need technical blog posts — use a technical writer agent
• You need API design (not just documentation) — use an API navigator agent
• You need code comments specifically — use a code reviewer agent

Quick Start

Copy
# .claude/agents/documentation-engineer.yml
name: Documentation Engineer Partner
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Documentation engineering agent for creating API docs, tutorials, architecture guides, and doc automation

Example invocation:

claude "Create a comprehensive getting-started guide for our SDK that covers installation, authentication, making your first API call, error handling, and pagination"

Core Concepts

Documentation Types

Type	Audience	Purpose	Update Frequency
API Reference	Developers integrating	Exact endpoints, params, responses	Every API change
Getting Started	New users	First success in < 5 minutes	Major version changes
Tutorials	Learning developers	Step-by-step guided projects	Quarterly
How-To Guides	Experienced developers	Solve specific problems	As needed
Architecture Docs	Team members	System design decisions	Major refactors
Runbooks	On-call engineers	Incident response procedures	After each incident

Documentation Structure (Diátaxis Framework)

                     Practical          Theoretical
                 ┌──────────────────┬──────────────────┐
  Learning       │    Tutorials     │   Explanation     │
  Oriented       │  "Follow along"  │  "Understand why" │
                 ├──────────────────┼──────────────────┤
  Task           │   How-To Guides  │    Reference      │
  Oriented       │  "Solve problem" │  "Look up facts"  │
                 └──────────────────┴──────────────────┘

Configuration

Parameter	Description	Default
doc_platform	Documentation tool (docusaurus, mkdocs, gitbook)	docusaurus
api_spec_format	API documentation format (openapi3, asyncapi)	openapi3
code_doc_tool	Code documentation generator (typedoc, jsdoc, sphinx)	typedoc
style_guide	Writing style (google, microsoft, custom)	google
output_format	Output format (markdown, mdx, rst)	markdown

Best Practices

1. Follow the Diátaxis framework for documentation organization. Separate tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), and explanation (understanding-oriented). Mixing these types in a single page confuses readers who have different goals.

2. Every API endpoint needs a working code example. Developers copy-paste before they read. Provide complete, runnable examples in at least two languages that handle authentication, make the request, parse the response, and handle common errors.

3. Test your documentation like you test code. Run code examples in CI, validate OpenAPI specs, check for broken links, and verify that installation instructions work on a clean environment. Untested documentation is unreliable documentation.

4. Write for scanning, not reading. Use descriptive headings, bullet points, code blocks, tables, and callout boxes. Most developers scan for the specific information they need — make it easy to find without reading everything sequentially.

5. Keep documentation close to the code it describes. API documentation generated from code annotations (JSDoc, Python docstrings, Go doc comments) stays current automatically. The farther documentation lives from the code, the faster it becomes stale.

Common Issues

Documentation becomes stale within weeks of writing. Manual documentation maintenance doesn't scale. Automate what you can — generate API docs from OpenAPI specs, extract type definitions from TypeScript, and run doc-testing in CI that fails when examples break.

New developers can't follow the getting-started guide. Guides written by experts skip steps that feel obvious. Have a new team member follow the guide on a clean machine and document every point where they get stuck. Fix those gaps and repeat quarterly.

Documentation search returns irrelevant results. Poor search is often caused by duplicated content, missing metadata, or weak headings. Deduplicate content aggressively (link instead of copy), add frontmatter tags, and use descriptive section headings that match how developers phrase their questions.