documentation

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

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

# 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

# [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)

# 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