Robocoding and You

Jan 12

Many tech writers are grappling with AI. Some see it as a threat. I see it as a force multiplier. After ten years documenting APIs and technical products, I've started experimenting with AI tools like Cline and Claude. The results? AI generates solid structure fast, but it needs a human writer to make it actually useful to other humans. Here's what that looks like in practice.

AI tools like Cline, combined with VS Code can help you spit out API documentation in no time. However, the tone (and the helpfulness) will be off. Sure, it may be technically accurate, but it’s kind of like have 95-year-old drill sergeant give you your answers: no explanations, no “why”s behind the answers, just DO THIS AND SIT DOWN. Here’s a sample of what Cline spit out for a test API:

# API Reference - Tasks

## Create Task

Creates a new task in the system.

### Endpoint

```
POST /api/v1/tasks

### Authentication

This endpoint requires authentication. Include a valid authentication token in your request headers.

### Request Headers

| Header | Value | Required | |--------|-------|----------| | Content-Type | application/json | Yes | | Authorization | Bearer {token} | Yes |

### Request Body

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | Yes | The title of the task | | description | string | No | Detailed description of the task | | priority | string | Yes | Task priority level. Must be one of: "low", "medium", or "high" | | due_date | string | Yes | Task due date in YYYY-MM-DD format | | assignee_id | integer | Yes | The ID of the user to whom the task is assigned |

### Example Request

curl -X POST https://api.example.com/api/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token_here" \
  -d '{
    "title": "Complete API documentation",
    "description": "Write comprehensive documentation for all REST API endpoints",
    "priority": "high",
    "due_date": "2026-02-15",
    "assignee_id": 42
  }'

### Success Response

**Status Code:** 201 Created

Returns the newly created task object.

#### Response Body

| Field | Type | Description | |-------|------|-------------| | id | integer | Unique identifier for the task | | title | string | Task title | | description | string | Task description (null if not provided) | | priority | string | Task priority level | | due_date | string | Task due date in YYYY-MM-DD format | | assignee_id | integer | ID of the assigned user | | status | string | Current task status (default: "pending") | | created_at | string | ISO 8601 timestamp of task creation |

#### Example Response

{
  "id": 1234,
  "title": "Complete API documentation",
  "description": "Write comprehensive documentation for all REST API endpoints",
  "priority": "high",
  "due_date": "2026-02-15",
  "assignee_id": 42,
  "status": "pending",
  "created_at": "2026-01-12T19:11:54Z"
}

### Error Responses

#### 400 Bad Request

The request body contains invalid data or is malformed.

**Example Response:**

{
  "error": "Bad Request",
  "message": "Invalid priority value. Must be 'low', 'medium', or 'high'",
  "status": 400
}

**Common Causes:** - Missing required fields (title, priority, due_date, assignee_id) - Invalid priority value (not one of: low, medium, high) - Invalid due_date format (must be YYYY-MM-DD) - Invalid data types (e.g., string instead of integer for assignee_id)

#### 401 Unauthorized

Authentication credentials are missing or invalid.

**Example Response:**

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token",
  "status": 401
}

#### 404 Not Found

The specified assignee does not exist.

**Example Response:**

{
  "error": "Not Found",
  "message": "User with ID 42 not found",
  "status": 404
}

### Notes

All timestamps are returned in ISO 8601 format (UTC)

The status field is automatically set to "pending" for newly created tasks

The description field can be an empty string or omitted entirely

Date validation ensures the due_date is a valid calendar date

The system validates that the assignee_id corresponds to an existing user

### Rate Limiting

This endpoint is subject to standard API rate limits. Refer to the [Rate Limiting Guide](rate-limiting.md) for more information.

What's missing?

The AI gave me technically accurate documentation. Developers need help, not just a list of technically correct answers. Sure, I get some error messages, but they essentially just say “you’re wrong.” With a few minutes of finessing, writers can turn a quick build into something far more useful whoever’s two cans of Monsters deep staring at their screen at 2am. Devs need to know:

- What do I do with the response I get back?

- How do I fix errors when things go wrong?

- Where do I get the data this endpoint needs?

So I spent 15 minutes improving it. Here's what changed:

# API Reference - Tasks

## Create Task

Creates a new task in the system.

### Endpoint

```

POST /api/v1/tasks

```

### Authentication

This endpoint requires authentication. Include a valid authentication token in your request headers.

### Request Headers

| Header | Value | Required |

|--------|-------|----------|

| `Content-Type` | `application/json` | Yes |

| `Authorization` | `Bearer {token}` | Yes |

### Request Body

| Parameter | Type | Required | Description |

|-----------|------|----------|-------------|

| `title` | string | Yes | The title of the task |

| `description` | string | No | Detailed description of the task |

| `priority` | string | Yes | Task priority level. Must be one of: `"low"`, `"medium"`, or `"high"` |

| `due_date` | string | Yes | Task due date in `YYYY-MM-DD` format |

| `assignee_id` | integer | Yes | The ID of the user to whom the task is assigned |

### Example Request

```bash

curl -X POST https://api.example.com/api/v1/tasks \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer your_access_token_here" \

  -d '{

    "title": "Complete API documentation",

    "description": "Write comprehensive documentation for all REST API endpoints",

    "priority": "high",

    "due_date": "2026-02-15",

    "assignee_id": 42

}'

```

### Success Response

**Status Code:** `201 Created`

Returns the newly created task object.

**Next Steps:**

Use the returned `id` field to reference this task in subsequent API calls:

- Update task: `PATCH /api/v1/tasks/1234`

- Get task details: `GET /api/v1/tasks/1234`

- Delete task: `DELETE /api/v1/tasks/1234`

#### Response Body

| Field | Type | Description |

|-------|------|-------------|

| `id` | integer | Unique identifier for the task |

| `title` | string | Task title |

| `description` | string | Task description (null if not provided) |

| `priority` | string | Task priority level |

| `due_date` | string | Task due date in `YYYY-MM-DD` format |

| `assignee_id` | integer | ID of the assigned user |

| `status` | string | Current task status (default: `"pending"`) |

| `created_at` | string | ISO 8601 timestamp of task creation |

#### Example Response

```json

  "id": 1234,

  "title": "Complete API documentation",

  "description": "Write comprehensive documentation for all REST API endpoints",

  "priority": "high",

  "due_date": "2026-02-15",

  "assignee_id": 42,

  "status": "pending",

  "created_at": "2026-01-12T19:11:54Z"

```

### Error Responses

#### 400 Bad Request

The request body contains invalid data or is malformed.

**Example Response:**

```json

  "error": "Bad Request",

  "message": "Invalid priority value. Must be 'low', 'medium', or 'high'",

  "status": 400

```

**Common Causes:**

- **Missing required fields:** Ensure your request includes `title`, `priority`, `due_date`, and `assignee_id`

- **Invalid priority value:** Must be exactly `"low"`, `"medium"`, or `"high"` (lowercase, in quotes). Example: `"priority": "high"`

- **Invalid due_date format:** Must follow `YYYY-MM-DD` format. Example: `"due_date": "2026-01-15"` (not "01/15/2026" or "15-01-2026")

- **Invalid data types:** `assignee_id` must be an integer (number without quotes). Example: `"assignee_id": 42` not `"assignee_id": "42"`

#### 401 Unauthorized

Your authentication token is missing, invalid, or expired.

**How to fix:**

1. Verify you included the `Authorization` header in your request

2. Check that your token hasn't expired (tokens are valid for 24 hours)

3. If expired, obtain a new token via `POST /auth/login`

4. Ensure the format is: `Authorization: Bearer YOUR_TOKEN` (with "Bearer " prefix)

**Example Response:**

```json

  "error": "Unauthorized",

  "message": "Token expired. Please authenticate again.",

  "status": 401

```

#### 404 Not Found

The specified assignee does not exist. Double check the user ID you're using. You can list users by

- Using `GET /api/v1/users` to retrieve a list of valid, active users

- Ensure the `assignee_id` matches an existing user's `id`

- Verify the user's status is `"active"`

**Finding Valid User IDs:**

First, retrieve active users to get valid `assignee_id` values:

```bash

curl -X GET https://api.example.com/api/v1/users \

  -H "Authorization: Bearer your_access_token_here"

```

Then create your task using an active user's ID.

**Example Response:**

```json

  "error": "Not Found",

  "message": "User with ID 42 not found",

  "status": 404

```

### Notes

- All timestamps are returned in ISO 8601 format (UTC)

- The `status` field is automatically set to `"pending"` for newly created tasks

- The `description` field can be an empty string or omitted entirely

- Date validation ensures the `due_date` is a valid calendar date

- The system validates that the `assignee_id` corresponds to an existing user

### Rate Limiting

This endpoint is subject to standard API rate limits. Refer to the [Rate Limiting Guide](rate-limiting.md) for more information.

Key improvements I made:

1. Added workflow context - The "Next Steps" section shows developers what to do with the task ID they receive.

2. Made errors actionable - Instead of just saying "Invalid priority value," I showed exactly what valid values look like with examples.

3. Connected related endpoints - Explained how to use GET /users to find valid assignee IDs before creating tasks.

4. Anticipated confusion - Added counter-examples showing common mistakes, like putting quotes around integers.

Time investment: Cline generated the initial docs in about 2 minutes. I spent 15 minutes making them developer-friendly. That's still 85% faster than starting from scratch, and the result is more useful than what I would've written manually in an hour.

The bottom line: AI won't replace technical writers. But technical writers who use AI will replace those who don't.

The skill isn't in typing documentation, it's understanding what makes documentation useful and knowing how to get there.

Shawn McGowan