d-o-hub Technical Writing
Quick Start
- Understand your audience - See writing-tips.md
- Choose document type - See templates.md
- Write and review - Follow guidelines below
Document Types
| Type | Use For |
|---|---|
| Technical Spec | Feature designs, technical decisions |
| Architecture Doc | System design, component overview |
| Runbook | Operations, deployment, troubleshooting |
| API Docs | REST/gRPC endpoints, integrations |
| Changelog | Release notes, version history |
Core Guidelines
Clarity
- Use simple, direct language
- One idea per sentence
- Define technical terms
- Avoid jargon when possible
Structure
- Use hierarchical headings (H1, H2, H3)
- Break content into sections
- Use lists for multiple items
- Use tables for structured data
Completeness
- Cover prerequisites
- Include error handling
- Document edge cases
- Explain why, not just how
Templates
See templates.md for:
- Technical specification template
- Architecture document template
- Runbook template
- API documentation template
- Changelog template
Writing Tips
See writing-tips.md for:
- Active voice vs passive voice
- Concise language examples
- Breaking down complexity
- Common mistakes to avoid
- Audience-specific guidance
- Visual aid examples (Mermaid diagrams, code blocks)
Review Checklist
- Clear purpose stated upfront
- Logical flow of information
- All terms defined
- Code examples tested
- Links work
- Diagrams are clear
- Consistent formatting
- Table of contents (if long)
- Last updated date