# Documentation

> Technical writing patterns for READMEs, runbooks, and architecture docs, with accuracy verification. Use when writing documentation, creating runbooks, or documenting system architecture.

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

---


# Documentation

Use these patterns when writing documentation, creating runbooks, or documenting system architecture.

## MCP Servers & Plugins

| Resource | When to Use |
|---|---|
| `deploy-on-aws` diagram skill | Generate architecture diagrams for system documentation and runbooks |
| `deploy-on-aws:awsknowledge` | Reference AWS service docs when writing architecture docs or runbooks — use `read_documentation`, `search_documentation`, and `recommend` to link to official docs rather than paraphrasing |
| `aws-serverless` plugin | Use `get_lambda_guidance` and `get_serverless_templates` to document serverless patterns, Lambda configurations, and SAM deployment steps |
| `databases-on-aws` plugin | Use `dsql_search_documentation` and `dsql_recommend` to document DSQL schema design, query patterns, and migration procedures |
| `context7` MCP | Look up library/framework docs to verify technical accuracy in README examples |
| `pr-review-toolkit:comment-analyzer` plugin | After writing any documentation — verifies accuracy, staleness risk, and maintainability |
| `gh` CLI | Link to issues, PRs, and discussions from documentation; create issues for documentation gaps (`gh issue create`) |

## README Structure

```markdown
# Project Name

One-line description of what this does.

## Quick Start

\`\`\`bash
npm install
npm start
\`\`\`

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |

## Usage

[Examples of common operations]

## Development

[How to set up dev environment, run tests]

## License

MIT
```

## API Documentation

Use OpenAPI/Swagger. Minimum per endpoint:
- HTTP method and path
- Request parameters (path, query, body)
- Response codes and schemas
- Authentication requirements
- Example request/response

## Runbook Template

```markdown
# [Service Name] Runbook

## Overview
What this service does, who owns it.

## Architecture
[Use `deploy-on-aws` diagram skill to generate architecture diagram]

## Health Checks
- Endpoint: `GET /health`
- Expected: 200 OK

## Common Issues

### Issue: High latency
**Symptoms**: Response times > 500ms
**Diagnosis**: Check DB connections, cache hit rate
**Resolution**: Scale horizontally, clear cache

## Escalation
- L1: On-call engineer
- L2: Service owner
- L3: Platform team
```

## Architecture Decision Record (ADR)

```markdown
# ADR-001: Use PostgreSQL for user data

## Status
Accepted

## Context
Need persistent storage for user accounts.

## Decision
Use PostgreSQL on RDS.

## Consequences
- Pro: ACID compliance, familiar tooling
- Con: Operational overhead vs DynamoDB
```

## Spec Artifact Documentation

When documenting within the spec-driven workflow, these artifacts have defined formats (see `spec-workflow` skill):

| Artifact | Owner | Purpose |
|----------|-------|---------|
| `spec.md` | fullstack-agent | Design decisions, constraints, alternatives considered |
| `design.md` | fullstack-agent | Architecture, repo structure, infrastructure design |
| `tasks.md` | fullstack-agent (authored), all teammates (updated) | Parallelized task groups with completion notes |
| `review.md` | review-agent | Severity-rated findings with PASS/FAIL verdict |
| `sa-review.md` | sa-agent | Well-Architected findings by pillar, cost estimates |
| `decisions.md` | any agent via fullstack-agent | Mid-flight decisions to prevent re-litigation |

When writing documentation for a project that uses the spec workflow, link to relevant specs rather than duplicating their content.

## Agent Integration

- `devops-agent` owns READMEs, runbooks, and architecture docs — keeps them next to the code they describe
- `coding-agent` writes inline documentation (function/class/module docs) during implementation
- Both agents delegate to `pr-review-toolkit:comment-analyzer` after writing docs to verify accuracy
- `sa-agent` produces architecture review documentation in Well-Architected pillar format, claims and tracks tasks like other teammates
- Use the `gh` CLI (`gh issue create`) to create issues for documentation that needs future updates (e.g., after API changes)

## Writing Tips

- Lead with the "what" and "why"
- Use concrete examples over abstract explanations
- Keep it scannable (headers, bullets, tables)
- Update docs when code changes (or automate it)
- Docs are concise and actionable — no filler
- Use the `deploy-on-aws` diagram skill for architecture diagrams — don't describe what a diagram can show
- Use `WebFetch` (or your platform's equivalent) to load external specs or references rather than copy-pasting content