Document Writer
Purpose
Provides expertise in creating structured technical documentation for software systems. Specializes in architectural decision records, RFCs, design documents, and knowledge base articles.
When to Use
- Writing architectural decision records (ADRs)
- Creating RFC (Request for Comments) documents
- Documenting system designs
- Writing technical specifications
- Creating runbooks and playbooks
- Building internal knowledge bases
- Documenting incidents (post-mortems)
Quick Start
Invoke this skill when:
- Writing architectural decision records (ADRs)
- Creating RFC documents
- Documenting system designs
- Writing technical specifications
- Creating runbooks and playbooks
Do NOT invoke when:
- Writing API documentation (use api-documenter)
- Writing user-facing docs (use technical-writer)
- Creating Word documents (use docx-skill)
- Writing marketing content (use content-marketer)
Decision Framework
Document Type Selection:
├── Decision needed → ADR
├── Proposal for review → RFC
├── System explanation → Design doc
├── How to operate → Runbook
├── Incident occurred → Post-mortem
├── Process definition → SOP
└── Knowledge capture → Wiki articleCore Workflows
1. ADR Creation
- Identify decision to be made
- List context and constraints
- Enumerate options considered
- Analyze pros and cons
- State decision and rationale
- Document consequences
- Get stakeholder review
2. RFC Process
- Write problem statement
- Propose solution approach
- Detail implementation plan
- Address risks and mitigations
- Define success metrics
- Open for comments
- Iterate based on feedback
- Move to accepted/rejected
3. Design Document
- State purpose and scope
- Describe current state
- Present proposed design
- Include diagrams (C4, sequence)
- Address non-functional requirements
- List alternatives considered
- Define rollout plan
Best Practices
- Use templates for consistency
- Include diagrams for complex systems
- Write for the reader, not yourself
- Keep documents updated
- Link related documents
- Version control all documentation
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| No template | Inconsistent docs | Use standard templates |
| Write-only docs | Never updated | Schedule reviews |
| Missing context | Readers confused | Include background |
| Too verbose | Nobody reads | Be concise, link details |
| Undiscoverable | Docs go unused | Organize and index |