technical-writing

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: technical-writing
description: Technical documentation best practices for clear, accurate, and useful documentation. Use when writing documentation, README files, API docs, architecture guides, or any technical communication.
---

# Technical Writing Skill

## Core Principle

**Write for your audience, not for yourself.**

Technical documentation exists to help others understand and use your work. Good documentation:
- **Answers questions** before they're asked
- **Shows, doesn't just tell** (examples over abstract descriptions)
- **Stays current** (outdated docs are worse than no docs)
- **Is findable** (organized and searchable)

---

## Documentation Types

### 1. README Files

**Purpose:** First impression and quick-start guide

**Essential sections:**
```markdown
# Project Name

One-sentence description of what this project does.

## What It Does

2-3 sentences explaining the purpose and value.

## Quick Start

    npm install
    npm start
    # Now visit http://localhost:3000

## Installation

Detailed setup instructions.

## Usage

Common examples and use cases.

## Documentation

Link to full docs if they exist elsewhere.

## Contributing

How to contribute (if applicable).

## License

License information.
```

---

### 2. API Documentation

**Purpose:** How to use your API/library

**Essential elements:**
- Function/method signature
- Parameters with types
- Return value with type
- Examples
- Error conditions

**Example:**
```python
def calculate_discount(price: float, coupon_code: str) -> float:
    """
    Calculate the discounted price based on coupon code.

    Args:
        price: Original price in USD (must be positive)
        coupon_code: Coupon code (e.g., "SAVE10", "FREESHIP")

    Returns:
        Discounted price in USD

    Raises:
        ValueError: If price is negative
        CouponError: If coupon code is invalid or expired

    Examples:
        >>> calculate_discount(100.0, "SAVE10")
        90.0

        >>> calculate_discount(50.0, "FREESHIP")
        50.0  # Doesn't affect price

    Note:
        Coupon codes are case-insensitive. Free shipping coupons
        don't affect the returned price.
    """
```

---

### 3. How-To Guides

**Purpose:** Step-by-step instructions for specific tasks

**Structure:**
```markdown
# How to Deploy to Production

## Prerequisites

- Docker installed (v20+)
- AWS CLI configured
- Production credentials

## Steps

### 1. Build the Docker image

    docker build -t myapp:latest .

### 2. Tag for ECR

    docker tag myapp:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp:latest

### 3. Push to ECR

    docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp:latest

### 4. Update ECS service

    aws ecs update-service --cluster prod --service myapp --force-new-deployment

### 5. Verify deployment

    curl https://myapp.com/health
    # Should return: {"status": "healthy"}

## Troubleshooting

**Issue:** Docker build fails with "out of space"

**Solution:** Clean up old images: `docker system prune -a`

---

**Issue:** ECS deployment stuck at 50%

**Solution:** Check CloudWatch logs for errors in new tasks
```

---

### 4. Architecture Documentation

**Purpose:** Explain system design and decisions

**Essential elements:**
- System overview diagram
- Component responsibilities
- Data flow
- Key decisions and trade-offs
- Non-obvious constraints

**Example:**
```markdown
# Authentication System Architecture

## Overview

We use JWT-based authentication with refresh tokens for stateless,
scalable authentication across microservices.

## Components

┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│   Client    │──────▶│  Auth API   │──────▶│  User DB    │
└─────────────┘       └─────────────┘       └─────────────┘
      │                      │
      │ Access Token         │ Verify Token
      ▼                      ▼
┌─────────────┐       ┌─────────────┐
│Resource API │◀──────│  API Gateway│
└─────────────┘       └─────────────┘

###