technical-writing

SKILL.md

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

1. **Assuming knowledge**: Define terms, explain context
2. **Outdated docs**: Keep in sync with code
3. **Missing examples**: Always include examples
4. **No visuals**: Use diagrams for complex concepts
5. **Poor structure**: Use headings and sections
6. **Passive voice**: Use active voice
7. **Too much jargon**: Write for your audience
8. **No version info**: Date docs, note versions
9. **Missing error cases**: Document what can go wrong
10. **No maintenance**: Update regularly

## Best practices

1. **Write for your audience**: Match their knowledge level
2. **Start with why**: Explain the purpose
3. **Show, don't just tell**: Use examples
4. **Be consistent**: Terminology, style, structure
5. **Test your docs**: Can someone follow them?
6. **Version your docs**: Track with code versions
7. **Use templates**: Consistency across docs
8. **Link related docs**: Help readers find more info
9. **Update with code**: Docs are part of the code
10. **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)

## Examples

### Example 1: Basic usage
<!-- Add example content here -->

### Example 2: Advanced usage
<!-- Add advanced example content here -->