Technical Writer

What this skill does

# Technical Writer

Great documentation is the difference between a product people use and a product people abandon.

## Core Principle

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

Good documentation:

- Answers questions before they're asked
- Gets users to success quickly
- Reduces support burden
- Scales knowledge across teams

---

## Documentation Types

### 1. API Documentation

**Audience:** Developers integrating your API
**Goal:** Enable integration without support

### 2. User Guides

**Audience:** End users
**Goal:** Help users accomplish tasks

### 3. Tutorials

**Audience:** Learners
**Goal:** Teach concepts through practice

### 4. Reference Documentation

**Audience:** Developers needing specifics
**Goal:** Quick lookup of parameters, methods

### 5. Architecture Documentation

**Audience:** Engineers maintaining system
**Goal:** Understand system design decisions

---

## Phase 1: API Documentation

### OpenAPI / Swagger Specification

```yaml
# openapi.yaml
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1
    description: Production server

paths:
  /users:
    get:
      summary: List all users
      description: Returns a paginated list of users
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  format: email
                  example: [email protected]
                name:
                  type: string
                  example: John Doe
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer

  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized

    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              details:
                type: array
                items:
                  type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []
```

### API Documentation Structure

```markdown
# User API

## Authentication

All API requests require authentication using a Bearer token:
```

Authorization: Bearer YOUR_API_KEY

```

Get your API key from the [dashboard](https://dashboard.example.com).

## Base URL

```

https://api.example.com/v1

```

## Rate Limiting

- 100 requests per minute per API key
- 1000 requests per hour per API key

Rate limit headers:
```

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640000000

````

## Errors

Standard HTTP status codes:

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

Error response format:
```json
{
  "error": "Invalid email format",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "email",
    "message": "Must be a valid email address"
  }
}
````

## Endpoints

### List Users

```
GET /users
```

Returns a paginated list of users.

**Query Parameters:**

| Parameter | Type    | Default    | Description              |
| --------- | ------- | ---------- | ------------------------ |
| page      | integer | 1          | Page number              |
| limit     | integer | 20         | Items per page (max 100) |
| sort      | string  | created_at | Sort field               |
| order     | string  | desc       | Sort order (asc/desc)    |

**Example Request:**

```bash
curl -X GET "https://api.example.com/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Example Response:**

```json
{
  "data": [
    {
      "id": "usr_123",
      "email": "[email protected]",
      "name": "John Doe",
      "createdAt": "2024-01-22T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}
```

### Create User

```
POST /users
```

Creates a new user.

**Request Body:**

```json
{
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user"
}
```

**Parameters:**

| Field | Type   | Required | Description               |
| ----- | ------ | -------- | ------------------------- |
| email | string | Yes      | User email address        |
| name  | string | Yes      | User full name            |
| role  | string | No       | User role (default: user) |

**Example Request:**

```bash
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe"
  }'
```

**Example Response:**

```json
{
  "id": "usr_123",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "createdAt": "2024-01-22T10:30:00Z"
}
```

## SDKs

### JavaScript / TypeScript

```bash
npm install @example/api-client
```

```typescript
import { ExampleAPI } from '@example/api-client'

const client = new ExampleAPI('YOUR_API_KEY')

// List users
const users = await client.users.list({ page: 1, limit: 20 })

// Create user
const user = await client.users.create({
  email: '[email protected]',
  name: 'John Doe'
})
```

### Python

```bash
pip install example-api
```

```python
from example_api import Client

client = Client('YOUR_API_KEY')

# List users
users = client.users.list(page=1, limit=20)

# Create user
user = client.users.create(
    email='[email protected]',
    name='John Doe'
)
```

## Webhooks

Subscribe to events via webhooks:

```json
{
  "url": "https://yourdomain.com/webhook",
  "events": ["user.created", "user.updated", "user.deleted"]
}
```

Webhook payload:

```json
{
  "event": "user.created",
  "timestamp": "2024-01-22T10:30:00Z",
  "data": {
    "id": "usr_123",
    "email": "[email protected]"
  }
}
```

## Changelog

### v1.1.0 (2024-01-22)

- Added `sort` and `order` parameters to list endpoint