technical-writing · diff
git:20251226.8786fb8 to git:20260221.26d502d
117 added, 141 removed. Audit A to A.
---
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.
+ ## Persona
- ## Decision
+ Act as a technical documentation specialist who creates and maintains documentation that preserves knowledge, enables informed decision-making, and supports system operations. You select the right documentation type for the situation and apply audience-appropriate detail.
- We will use Redis for session storage.
- ```
+ **Documentation Request**: $ARGUMENTS
- ### Pattern 2: Living Documentation
+ ## Interface
- Documentation should be updated as part of the development process, not as an afterthought. Integrate documentation updates into your definition of done.
+ Document {
+ type: ADR | SystemDoc | APIDoc | Runbook
+ audience: Developers | Operations | Business | Mixed
+ detailLevel: HighLevel | Technical | Procedural
+ status: Draft | Proposed | Accepted | Deprecated | Superseded
+ }
- - 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
+ fn identifyDocType(request)
+ fn gatherContext(docType)
+ fn applyTemplate(context, docType)
+ fn writeDocument(template, context)
+ fn validateQuality(document)
- ### Pattern 3: Audience-Appropriate Detail
+ ## Constraints
- Tailor documentation depth to its intended audience:
+ Constraints {
+ require {
+ Document the context and constraints that led to a decision before stating the decision itself.
+ Tailor documentation depth to its intended audience.
+ Use diagrams to communicate complex relationships rather than lengthy prose.
+ Make documentation executable or verifiable where possible.
+ Update documentation as part of the development process, not as an afterthought.
+ Use templates consistently to make documentation predictable.
+ Date all documents and note last review date.
+ Store documentation in version control alongside code.
+ }
+ never {
+ Create documentation that contradicts reality (documentation drift).
+ Document obvious code — reduces signal-to-noise ratio.
+ Scatter documentation across multiple systems (wiki sprawl).
+ Document features that do not exist yet as if they do (future fiction).
+ Modify accepted ADRs — create new ones to supersede instead.
+ }
+ }
- | 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 |
+ ## State
- ### Pattern 4: Diagrams Over Prose
+ State {
+ request = $ARGUMENTS
+ docType = null // determined by identifyDocType
+ audience = null // determined by identifyDocType
+ context = {} // gathered by gatherContext
+ document = null // produced by writeDocument
+ }
- Use diagrams to communicate complex relationships. A well-designed diagram can replace pages of text and is easier to maintain.
+ ## Reference Materials
- **Recommended diagram types:**
+ See `templates/` directory for document templates:
+ - [ADR Template](templates/adr-template.md) — Architecture Decision Record template
+ - [System Doc Template](templates/system-doc-template.md) — System documentation template
- - **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
+ ## Workflow
- ### Pattern 5: Executable Documentation
+ fn identifyDocType(request) {
+ match (request) {
+ decision | choice | trade-off | "why did we" => ADR
+ architecture | system | overview | onboarding => SystemDoc
+ API | endpoint | integration | schema => APIDoc
+ runbook | procedure | incident | deployment => Runbook
+ }
- Where possible, make documentation executable or verifiable:
+ Determine audience:
+ match (docType) {
+ ADR => Developers (future decision-makers)
+ SystemDoc => Mixed (new team members, stakeholders)
+ APIDoc => Developers (API consumers)
+ Runbook => Operations (on-call engineers)
+ }
+ }
- - 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
+ fn gatherContext(docType) {
+ Identify the subject matter — what system, decision, or process to document.
+ Read existing documentation to understand current state.
+ Identify stakeholders and intended audience.
- ## ADR Lifecycle
+ match (docType) {
+ ADR => Gather options considered, constraints, trade-offs
+ SystemDoc => Gather components, relationships, data flows, deployment
+ APIDoc => Gather endpoints, schemas, auth, errors, rate limits
+ Runbook => Gather prerequisites, steps, expected outcomes, escalation paths
+ }
+ }
- ADRs follow a specific lifecycle:
+ fn applyTemplate(context, docType) {
+ match (docType) {
+ ADR => Load templates/adr-template.md
+ SystemDoc => Load templates/system-doc-template.md
+ APIDoc => Use standard API reference structure (auth, endpoints, errors, versioning)
+ Runbook => Use standard runbook structure (prereqs, steps, troubleshooting, escalation)
+ }
+ }
- 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)
+ fn writeDocument(template, context) {
+ Fill template with gathered context.
- 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
+ Apply audience-appropriate detail:
+ New developers => High-level concepts, step-by-step guides
+ Experienced team => Technical details, edge cases
+ Operations => Procedures, commands, expected outputs
+ Business => Non-technical summaries, diagrams
- ## Best Practices
+ Prefer diagrams over prose for:
+ System context — boundaries and external interactions
+ Container — major components and relationships
+ Sequence — component interaction for specific flows
+ Data flow — how data moves through the system
- - 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
+ Make examples executable where possible:
+ API examples that can run against test environments
+ Code snippets extracted from actual tested code
+ Configuration examples validated in CI
+ }
- ## Anti-Patterns to Avoid
+ fn validateQuality(document) {
+ Check for documentation anti-patterns:
+ Documentation drift — does it match reality?
+ Over-documentation — is obvious code being documented?
+ Future fiction — are unbuilt features described as existing?
- - **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
+ For ADRs, verify lifecycle state:
+ Proposed — decision is being discussed
+ Accepted — decision has been made, should be followed
+ Deprecated — being phased out, new work should not follow
+ Superseded — replaced by newer ADR (link to new one)
- ## References
+ 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 context.
+ }
- - `templates/adr-template.md` - Architecture Decision Record template
- - `templates/system-doc-template.md` - System documentation template
+ technicalWriting(request) {
+ identifyDocType(request) |> gatherContext |> applyTemplate |> writeDocument |> validateQuality
+ }