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": "[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:

• 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]
**