technical-writing

Documentation Creation

A development skill for creating and maintaining technical documentation that preserves knowledge, enables informed decision-making, and supports system operations. This skill provides templates and patterns for common documentation needs.

When to Use

• Recording architectural or design decisions with context and rationale
• Documenting system architecture for new team members or stakeholders
• Creating API documentation for internal or external consumers
• Writing runbooks for operational procedures and incident response
• Capturing tribal knowledge before it's lost to team changes

Core Documentation Types

Architecture Decision Records (ADRs)

ADRs capture the context, options considered, and rationale behind significant architectural decisions. They serve as a historical record that helps future developers understand why the system is built a certain way.

When to create an ADR:

• Choosing between different technologies, frameworks, or approaches
• Making decisions that are difficult or expensive to reverse
• Establishing patterns that will be followed across the codebase
• Deprecating existing approaches in favor of new ones
• Any decision that a future developer might question

See: templates/adr-template.md

System Documentation

System documentation provides a comprehensive view of how a system works, its components, and their relationships. It helps new team members onboard and serves as a reference for operations.

Key elements:

• System overview and purpose
• Architecture diagrams showing component relationships
• Data flows and integration points
• Deployment architecture
• Operational requirements

See: templates/system-doc-template.md

API Documentation

API documentation describes how to interact with a service, including endpoints, request/response formats, authentication, and error handling.

Key elements:

• Authentication and authorization
• Endpoint reference with examples
• Request and response schemas
• Error codes and handling
• Rate limits and quotas
• Versioning strategy

Runbooks

Runbooks provide step-by-step procedures for operational tasks, from routine maintenance to incident response.

Key elements:

• Pre-requisites and access requirements
• Step-by-step procedures with expected outcomes
• Troubleshooting common issues
• Escalation paths
• Recovery procedures

Documentation Patterns

Pattern 1: Decision Context First

Always document the context and constraints that led to a decision before stating the decision itself. Future readers need to understand the "why" before the "what."

## Context

We need to store user session data that must be:
- Available across multiple application instances
- Retrieved in under 10ms
- Retained for 24 hours after last activity

Our current database is PostgreSQL, which would require additional
infrastructure for session management.

## Decision

We will use Redis for session storage.

Pattern 2: Living Documentation

Documentation should be updated as part of the development process, not as an afterthought. Integrate documentation updates into your definition of done.

• Update ADRs when decisions change (mark old ones as superseded)
• Revise system docs when architecture evolves
• Keep API docs in sync with implementation (prefer generated docs where possible)
• Review runbooks after each incident for accuracy

Pattern 3: Audience-Appropriate Detail

Tailor documentation depth to its intended audience:

Audience	Focus	Detail Level
New developers	Onboarding, getting started	High-level concepts, step-by-step guides
Experienced team	Reference, troubleshooting	Technical details, edge cases
Operations	Deployment, monitoring	Procedures, commands, expected outputs
Business stakeholders	Capabilities, limitations	Non-technical summaries, diagrams

Pattern 4: Diagrams Over Prose

Use diagrams to communicate complex relationships. A well-designed diagram can replace pages of text and is easier to maintain.

Recommended diagram types:

• System context: Shows system boundaries and external interactions
• Container: Shows major components and their relationships
• Sequence: Shows how components interact for specific flows
• Data flow: Shows how data moves through the system

Pattern 5: Executable Documentation

Where possible, make documentation executable or verifiable:

• API examples that can be run against a test environment
• Code snippets that are extracted from actual tested code
• Configuration examples that are validated in CI
• Runbook steps that have been recently executed

ADR Lifecycle

ADRs follow a specific lifecycle:

1. Proposed: Decision is being discussed, not yet accepted
2. Accepted: Decision has been made and should be followed
3. Deprecated: Decision is being phased out, new work should not follow it
4. Superseded: Decision has been replaced by a newer ADR (link to new one)

When superseding an ADR:

• Add "Superseded by ADR-XXX" to the old record
• Add "Supersedes ADR-YYY" to the new record
• Explain what changed and why in the new ADR's context

Best Practices

• Write documentation close to the code it describes (prefer docs-as-code)
• Use templates consistently to make documentation predictable
• Include diagrams for architecture; text for procedures
• Date all documents and note last review date
• Keep ADRs immutable once accepted (create new ones to supersede)
• Store documentation in version control alongside code
• Review documentation accuracy during code reviews
• Delete or archive documentation for removed features

Anti-Patterns to Avoid

• Documentation Drift: Docs that no longer match reality are worse than no docs
• Over-Documentation: Documenting obvious code reduces signal-to-noise
• Wiki Sprawl: Documentation scattered across multiple systems becomes unfindable
• Future Fiction: Documenting features that don't exist yet as if they do
• Write-Only Docs: Creating docs that no one reads or maintains

References

• templates/adr-template.md - Architecture Decision Record template
• templates/system-doc-template.md - System documentation template