Technical Writing When to use this skill Writing technical specifications Creating architecture documentation Documenting system designs Writing runbooks and operational guides Creating developer documentation API documentation User manuals and guides Release notes and changelogs Instructions Step 1: Understand your audience Developer audience : Focus on implementation details Include code examples Technical terminology is okay Show how, not just what DevOps/Operations audience : Focus on deployment and maintenance Include configuration examples Emphasize monitoring and troubleshooting Provide runbooks Manager/Stakeholder audience : High-level overview Business impact Minimal technical jargon Focus on outcomes End user audience : Simple, clear language Step-by-step instructions Visual aids (screenshots, videos) FAQ section Step 2: Choose the right document type Technical Specification :
[Feature Name] Technical Specification
Overview Brief description of what this spec covers
Problem Statement What problem are we solving?
Goals and Non-Goals
Goals
Goal 1
Goal 2
Non-Goals
What we're explicitly not doing
Solution Design
High-Level Architecture
Data Models
API Contracts
User Interface
Implementation Plan
Phase 1
Phase 2
Testing Strategy
Security Considerations
Performance Considerations
Monitoring and Alerting
Rollout Plan
Rollback Plan
Open Questions
References Architecture Document :
System Architecture
Overview High-level system description
Architecture Diagram [Insert diagram]
Components
Component 1
Responsibility
Technology stack
Interfaces
Component 2 ...
Data Flow How data moves through the system
Key Design Decisions
Decision 1
Context
Options considered
Decision made
Rationale
Technology Stack
Frontend: React, TypeScript
Backend: Python, FastAPI
Database: PostgreSQL
Infrastructure: AWS, Docker, Kubernetes
Scalability How the system scales
Security Authentication, authorization, data protection
Monitoring and Observability Metrics, logs, tracing
Disaster Recovery Backup and recovery procedures
Future Considerations Runbook :
[Service Name] Runbook
Service Overview What this service does
Dependencies
Service A
Service B
Database X
Deployment
- How to deploy
- ```bash
- ./deploy.sh production
- Rollback
- ./rollback.sh
- Monitoring
- Key Metrics
- Request rate
- Error rate
- Latency
- Dashboards
- Production Dashboard
- Alerts
- Common Issues
- Issue 1: High latency
- Symptoms
-
- Response time > 1s
- Diagnosis
-
- Check database connection pool
- Resolution
-
- Restart service or scale up
- Issue 2: Memory leak
- Symptoms
-
- Memory usage growing over time
- Diagnosis
-
- Check heap dump
- Resolution
- Restart service, investigate in staging Troubleshooting How to check logs kubectl logs -f deployment/service-name How to access metrics curl https://api/metrics Emergency Contacts On-call: PagerDuty Team Slack: #team-name API Documentation: ```markdown
API Documentation
Authentication
All requests require authentication: ```bash curl -H "Authorization: Bearer YOUR_TOKEN" \ https://api.example.com/endpoint Endpoints List Users GET /api/v1/users Parameters : Name Type Required Description page integer No Page number (default: 1) limit integer No Items per page (default: 20) Example Request : curl -X GET "https://api.example.com/api/v1/users?page=1&limit=20" \ -H "Authorization: Bearer YOUR_TOKEN" Example Response : { "data" : [ { "id" : 1 , "name" : "John Doe" , "email" : "john@example.com" } ] , "pagination" : { "page" : 1 , "limit" : 20 , "total" : 100 } } Error Responses : Status Description 400 Bad Request 401 Unauthorized 500 Server Error
Step 3: Writing guidelines
Clarity: - Use simple, direct language - One idea per sentence - Short paragraphs (3-5 sentences) - 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 - Add table of contents for long docs Examples: - Include code examples - Provide diagrams - Show before/after comparisons - Real-world scenarios Completeness: - Cover prerequisites - Include error handling - Document edge cases - Explain why, not just how - Link to related docs Consistency: - Consistent terminology - Consistent formatting - Consistent code style - Consistent structure
Step 4: Visual aids
Architecture diagrams (Mermaid): ```mermaid graph TB A[Client] -->|HTTP| B[Load Balancer] B --> C[Web Server 1] B --> D[Web Server 2] C --> E[Database] D --> E Sequence diagrams : sequenceDiagram Client ->> +Server : Request Server ->> +Database : Query Database -->> -Server : Data Server -->> -Client : Response Flowcharts : flowchart TD A [Start] --> B {Is valid?} B --> |Yes| C [Process] B --> |No| D [Error] C --> E [End] D --> E Code blocks with syntax highlighting: def calculate_total ( items : List [ Item ] ) -
Decimal : """Calculate total price of items.""" return sum ( item . price for item in items ) Screenshots : Use for UI documentation Annotate important parts Keep up-to-date with UI changes Tables : Parameter Type Default Description timeout int 30 Request timeout in seconds retries int 3 Number of retry attempts Step 5: Review and refine Self-review checklist : Clear purpose stated upfront Logical flow of information All terms defined Code examples tested Links work Diagrams are clear No typos or grammar errors Consistent formatting Table of contents (if needed) Last updated date Get feedback : Have someone from target audience review Test instructions (can they follow them?) Check for missing information Verify accuracy Maintain documentation : Update with code changes Version your docs Archive outdated docs Regular review cycle Document templates Technical Spec Template
- [Feature Name] Technical Spec
- **
- Author
- **
-
- [Your Name]
- **
- Date
- **
-
- [Date]
- **
- Status
- **
- [Draft/Review/Approved]
Overview [1-2 paragraphs describing what this document covers]
Background [Context and motivation]
Goals
Goal 1
Goal 2
Non-Goals
What we're not doing
Detailed Design [Technical details]
Alternatives Considered [Other approaches and why we didn't choose them]
Timeline
Week 1: ...
Week 2: ...
Open Questions
Question 1
Question 2
Features
Feature 1
Feature 2
Installation
Prerequisites
Node.js >= 14
npm >= 6
- Setup
- ```bash
- git clone https://github.com/user/project.git
- cd project
- npm install
- Usage
- npm
- start
- Configuration
- Environment variables:
- API_KEY
-
- Your API key
- PORT
- Server port (default: 3000) Development npm run dev npm test Deployment [Deployment instructions] Contributing [Contributing guidelines] License MIT
Changelog Template
```markdown
Changelog
[1.2.0] - 2024-01-15
Added
- New feature X
- Support for Y
Changed
- Improved performance of Z
- Updated dependency A to v2.0
Fixed
- Bug where user couldn't login
- Memory leak in background task
Deprecated
- Old API endpoint /v1/users (use /v2/users)
Removed
- Legacy authentication method
Security
- Fixed XSS vulnerability in comments
[1.1.0] - 2024-01-01
... Writing tips Use active voice ✅ Good: "The system sends a notification" ❌ Bad: "A notification is sent by the system" Be concise ✅ Good: "Click Save to save changes" ❌ Bad: "In order to save your changes, you should click on the Save button" Use examples ✅ Good: "Set the timeout in seconds: ```yaml timeout: 30 ❌ Bad: "Configure the timeout parameter appropriately"
Break down complexity
✅ Good: "To deploy: Build the image Push to registry Update deployment Verify rollout" ❌ Bad: "Deploy by building and pushing the image to the registry, then update the deployment and verify the rollout succeeded"
Common mistakes to avoid
- Assuming knowledge: Define terms, explain context
- Outdated docs: Keep in sync with code
- Missing examples: Always include examples
- No visuals: Use diagrams for complex concepts
- Poor structure: Use headings and sections
- Passive voice: Use active voice
- Too much jargon: Write for your audience
- No version info: Date docs, note versions
- Missing error cases: Document what can go wrong
- No maintenance: Update regularly
Best practices
- Write for your audience: Match their knowledge level
- Start with why: Explain the purpose
- Show, don't just tell: Use examples
- Be consistent: Terminology, style, structure
- Test your docs: Can someone follow them?
- Version your docs: Track with code versions
- Use templates: Consistency across docs
- Link related docs: Help readers find more info
- Update with code: Docs are part of the code
- Review regularly: Quarterly doc review
Tools
Diagram tools: - Mermaid (markdown-based) - Draw.io - Lucidchart - PlantUML Documentation platforms: - GitBook - Docusaurus - MkDocs - Sphinx Style checkers: - Grammarly - Hemingway Editor - Vale Screenshot tools: - Snagit - CloudApp - Loom (for videos)