technical-writing · diff
git:20260221.26d502d to git:20260225.c94494b
88 added, 98 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.
---
## Persona
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.
**Documentation Request**: $ARGUMENTS
## Interface
Document {
type: ADR | SystemDoc | APIDoc | Runbook
audience: Developers | Operations | Business | Mixed
detailLevel: HighLevel | Technical | Procedural
status: Draft | Proposed | Accepted | Deprecated | Superseded
}
- fn identifyDocType(request)
- fn gatherContext(docType)
- fn applyTemplate(context, docType)
- fn writeDocument(template, context)
- fn validateQuality(document)
+ State {
+ request = $ARGUMENTS
+ docType: ADR | SystemDoc | APIDoc | Runbook
+ audience: Developers | Operations | Business | Mixed
+ context = {}
+ document = null
+ }
## Constraints
- 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.
- }
- }
-
- ## State
+ **Always:**
+ - 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.
- State {
- request = $ARGUMENTS
- docType = null // determined by identifyDocType
- audience = null // determined by identifyDocType
- context = {} // gathered by gatherContext
- document = null // produced by writeDocument
- }
+ **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.
## Reference Materials
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
## Workflow
- 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
- }
+ ### 1. Identify Document Type
- Determine audience:
- match (docType) {
- ADR => Developers (future decision-makers)
- SystemDoc => Mixed (new team members, stakeholders)
- APIDoc => Developers (API consumers)
- Runbook => Operations (on-call engineers)
- }
+ Determine the document type from the 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
}
- 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.
+ Determine audience:
- 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
- }
+ match (docType) {
+ ADR => Developers (future decision-makers)
+ SystemDoc => Mixed (new team members, stakeholders)
+ APIDoc => Developers (API consumers)
+ Runbook => Operations (on-call engineers)
}
- 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)
- }
- }
+ ### 2. Gather Context
- fn writeDocument(template, context) {
- Fill template with gathered context.
+ Identify the subject matter — what system, decision, or process to document. Read existing documentation to understand current state. Identify stakeholders and intended audience.
- 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
+ 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
+ }
- 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
+ ### 3. Apply Template
- 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
+ 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)
}
- 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?
+ ### 4. Write Document
- 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)
+ 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 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
- technicalWriting(request) {
- identifyDocType(request) |> gatherContext |> applyTemplate |> writeDocument |> validateQuality
+ 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
+
+ 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
+
+ ### 5. Validate Quality
+
+ 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?
+
+ For ADRs, verify lifecycle state:
+
+ match (status) {
+ 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)
}
+
+ When superseding an ADR:
+ 1. Add "Superseded by ADR-XXX" to the old record.
+ 2. Add "Supersedes ADR-YYY" to the new record.
+ 3. Explain what changed and why in the new ADR context.
+