# Documentation Prompts That Produce Docs People Read

> Task-shaped headings, one runnable example, and the failure modes.

- **Author:** [Jessica Nguyen (@jessica_nguyen)](https://www.promptabide.com/jessica_nguyen)
- **Published:** 2026-06-20
- **Updated:** 2026-08-22
- **Tags:** `writing`, `documentation`, `developer-experience`
- **Views:** 611
- **Likes:** 551

## Prompt

```
Generated documentation defaults to a tour of the API surface, organised by class. Nobody reads that. People arrive with a task.

Prompt for the shape you want:

"Write docs for this module. Structure:
- One paragraph: what this is for and when NOT to use it
- Then sections titled as tasks ('Upload an image', 'Delete an image'), not as classes
- Each section: the shortest runnable example, then the parameters that example did not use
- A 'When this fails' section: the three most likely errors, what causes each, what to do
- No section that only restates the function signature

Examples must be copy-pasteable and complete — imports included."

"When NOT to use it" is the most valuable paragraph and it is never in generated docs unless you ask. Half of support questions are people using the wrong tool, and that paragraph answers them before they ask.
```

## Output

*Produced by Claude · claude-sonnet-4.*

```
## Upload an image

import { cloudinaryService } from "./services/cloudinary.service"

const url = await cloudinaryService.uploadFile(req.file, "posts/images")

Other options: `overwrite` (default false), `resource_type` (default "image").

## When this fails
- 401 api_secret mismatch — the secret is truncated; it is 27 chars.
- 400 Invalid image file — the client sent a PDF; validate mime type first.
```

---

Canonical HTML: https://www.promptabide.com/bides/docs-people-actually-read-jessica-nguyen-3
Agent guide: https://www.promptabide.com/llms.txt · https://www.promptabide.com/agent-instructions.md
Sitemap: https://www.promptabide.com/sitemap.xml