Docs from working code (without the marketing words)

If you ask an AI to "document this function," you get a paragraph that restates the signature, plus the words "powerful" and "flexible." Useless. The reader can already read the signature.

The prompt below is the writing prompt we use most often. It forces docs that explain what the type signature doesn't.

The pattern

Generate documentation for this code. Useful, not decorative.

[paste code, function, or module]

Audience: [junior on team / external API consumer / future me?]

Output sections (skip any that don't apply):
1. What it does — one sentence, no marketing
2. When to use it — and when NOT to (link to alternative if there is one)
3. Quick example — the simplest realistic call, with sample input and output
4. Parameters — table format, only ones non-obvious from the type signature
5. Common pitfalls — what trips people up
6. What it doesn't do — explicit non-goals

Skip:
- "This function takes X and returns Y" (that's the signature)
- "Powerful and flexible" or other marketing words
- Examples obvious from the function name

If there's no real reason to document this beyond the type signature, tell me and stop.

Why the closing line matters

"If there's no real reason to document this, tell me and stop" is the load-bearing instruction. Without it, the model will invent reasons to document trivial code. With it, it'll occasionally come back and say "the signature says it all" — which saves you a 200-word docstring nobody reads.

When this shines

• Documenting a public API for external consumers
• Writing a README section for a non-obvious utility
• Generating reference docs from existing handler functions
• Adding "when NOT to use this" to a deprecated-but-still-used helper

When to skip it

If the function is genuinely self-documenting (function add(a, b) { return a + b }), don't write docs for it. The prompt is good at telling you to stop, but you can also just not start.

The full version is on Writing prompts, along with nine other writing patterns we use weekly.