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
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
**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": "[email protected]"
}
],
"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:
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]
**
