home / skills / rsmdt / the-startup / technical-writing
This skill creates and maintains architectural decision records, system and API docs, and runbooks to preserve decisions and enable reliable operations.
npx playbooks add skill rsmdt/the-startup --skill technical-writingReview the files below or copy the command above to add this skill to your agents.
---
name: technical-writing
description: Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks. Use when capturing design decisions, documenting system architecture, creating API references, or writing operational procedures.
---
# 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."
```markdown
## 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
This skill creates and maintains technical documentation: architectural decision records (ADRs), system documentation, API references, and operational runbooks. It provides templates, patterns, and practical guidance to capture design rationale, onboard teams, and support operations. Use it to preserve knowledge and make engineering decisions traceable.
The skill supplies focused templates and documentation patterns for ADRs, system docs, API docs, and runbooks. It enforces documentation-life-cycle practices (proposed → accepted → deprecated → superseded), recommends diagram types, and promotes executable examples and docs-as-code workflows. It also suggests review points and version-control placement to keep docs current and discoverable.
When should I create an ADR instead of just a doc comment?
Create an ADR for significant decisions that are hard to reverse, affect multiple components, or establish cross-project patterns. Use doc comments for local implementation notes.
How do I keep runbooks reliable during incidents?
Keep runbooks short, step-by-step, and executable. Regularly rehearse procedures, validate commands in a safe environment, and update the runbook after each use or incident.
What level of diagram detail is appropriate?
Tailor diagrams to the audience: high-level system context for stakeholders, container or sequence diagrams for developers, and data-flow or deployment diagrams for operations.