Documentation Templates Complete

A comprehensive skill providing ready-to-use templates for all common documentation types in software projects. Covers READMEs, API docs, architecture docs, runbooks, changelogs, and onboarding guides with structure guidelines and examples.

When to Use This Skill

Choose this skill when:

• Creating documentation for a new project from scratch
• Standardizing documentation across multiple projects
• Writing specific document types (README, API reference, runbook)
• Establishing documentation templates for a team
• Reviewing existing documentation for completeness

Consider alternatives when:

• Writing documentation content → use a technical writing skill
• Building a documentation website → use a docs site generator skill
• Creating user-facing help articles → use a content strategy skill
• Writing inline code comments → handled during development

Quick Start

Copy
# README Template (Essential Sections)

# Project Name

Brief description — what this project does and why it exists.

## Quick Start

```bash
git clone <repo-url>
cd project-name
npm install
npm run dev

Features

• Feature 1: Brief description
• Feature 2: Brief description

Configuration

Variable	Required	Default	Description
DATABASE_URL	Yes	—	PostgreSQL connection string
API_KEY	Yes	—	Third-party API key
PORT	No	3000	Server port

Development

Copy
npm run dev     # Start development server
npm test        # Run test suite
npm run build   # Build for production

License

MIT

## Core Concepts

### Documentation Type Catalog

| Type | Audience | Updates | Template |
|------|----------|---------|----------|
| README | New developers | Every major change | Project orientation |
| Contributing Guide | Contributors | Annually | Contribution process |
| API Reference | API consumers | Every API change | Endpoint documentation |
| Architecture Doc | Team engineers | Quarterly | System design overview |
| Runbook | On-call engineers | After incidents | Operational procedures |
| Changelog | All users | Every release | Version history |
| ADR | Future engineers | Per decision | Decision records |
| Onboarding Guide | New team members | Quarterly | Team orientation |

### Architecture Document Template

```markdown
# Architecture: [System Name]

## Overview
What this system does in 2-3 sentences.

## System Context

[User] → [Web App] → [API Gateway] → [Services] ├── Auth Service → [User DB] ├── Order Service → [Order DB] └── Notification Service → [Email/SMS]

## Key Decisions
| Decision | Choice | Why | Date |
|----------|--------|-----|------|
| Database | PostgreSQL | ACID compliance, JSON support | 2024-01 |
| Queue | Redis Streams | Low latency, existing infra | 2024-02 |
| Auth | JWT + Refresh | Stateless, mobile support | 2024-01 |

## Data Flow
1. User submits order through web app
2. API Gateway validates JWT token
3. Order Service creates order record
4. Notification Service sends confirmation

## Deployment
- Infrastructure: AWS ECS Fargate
- CI/CD: GitHub Actions → ECR → ECS
- Environments: dev, staging, production

Runbook Template

Copy
# Runbook: [Service Name] - [Issue Type]

## When to Use
- Alert: "HighErrorRate" fires for service-x
- Symptom: Users report 500 errors on checkout

## Prerequisites
- AWS console access
- kubectl configured for production cluster
- Access to Grafana dashboards

## Diagnosis Steps

### Step 1: Check error rate
```bash
# View error rate in last 15 minutes
kubectl logs -l app=service-x --since=15m | grep ERROR | wc -l

Step 2: Check database connectivity

Copy
kubectl exec -it deploy/service-x -- pg_isready -h $DB_HOST

Step 3: Check memory/CPU

Copy
kubectl top pods -l app=service-x

Resolution

If database is unreachable:

1. Check RDS instance status in AWS console
2. Verify security group allows connections
3. Restart service: kubectl rollout restart deploy/service-x

If memory is high:

1. Scale up: kubectl scale deploy/service-x --replicas=4
2. Investigate memory leak (check heap dumps)

Escalation

• First 15 min: On-call engineer
• After 15 min: Engineering lead (@alice)
• After 30 min: VP Engineering (@bob)

## Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `templateFormat` | string | `'markdown'` | Format: markdown, notion, or confluence |
| `requiredSections` | string[] | `['overview', 'quickstart']` | Mandatory documentation sections |
| `readmeStyle` | string | `'minimal'` | README: minimal, standard, or comprehensive |
| `diagramTool` | string | `'mermaid'` | Diagrams: mermaid, ascii, or plantuml |
| `changelogFormat` | string | `'keepachangelog'` | Changelog format standard |
| `versioningScheme` | string | `'semver'` | Version: semver or date-based |

## Best Practices

1. **Start with the README — it's the front door of every project** — A project without a README is a project nobody can use. Cover what it does, how to install it, and how to run it. Everything else can come later.

2. **Keep runbooks actionable with copy-pasteable commands** — An on-call engineer at 3 AM needs commands they can copy and run, not conceptual explanations. Include exact commands with the expected output for each diagnostic step.

3. **Update documentation in the same PR as code changes** — Documentation that lives separately from code always drifts. Co-locating docs updates with code changes ensures they stay synchronized.

4. **Use templates consistently across all projects** — When every project uses the same README structure, engineers can find information instantly in any repository. Consistency reduces cognitive load.

5. **Delete outdated documentation rather than leaving it** — Wrong documentation is worse than no documentation. If a doc is outdated and nobody will update it, delete it and add a TODO to rewrite it when the feature stabilizes.

## Common Issues

**Documentation exists but nobody can find it** — Scattered across wikis, READMEs, Confluence, and Notion. Establish a single documentation hub with clear navigation. Link to it from every README.

**Runbooks are outdated and commands don't work** — Schedule quarterly runbook reviews. After every incident, update the runbook with what actually worked. Tag runbooks with "last verified" dates.

**Architecture diagrams don't match current system** — Generate diagrams from code (infrastructure-as-code, dependency graphs) rather than maintaining them manually. If manual, tie updates to architecture review cadence.