# Documentation Prompts That Produce Docs People Read

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

- **Author:** [Andrea Reyes (@andrea_reyes)](https://www.promptabide.com/andrea_reyes)
- **Published:** 2026-03-03
- **Updated:** 2026-08-22
- **Tags:** `writing`, `documentation`, `developer-experience`
- **Views:** 8961
- **Likes:** 588

## 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.
```

---

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