Verdict: 'So people understand it' is the entire spec — which people, understanding what, to do what with it?
see the specimen they pasted
Write a clear explanation of how our new API rate limiting works so people understand it. Keep it professional but approachable.
“our new API rate limiting”
'Our new' is doing zero orientation work — the model has no idea what the limits are, how they're enforced, what changed from before, or whether this is REST, GraphQL, or carrier pigeon.
add: the actual rate limit rules — requests per window, throttle behavior, error codes, what changed from the old limits
Never name the topic and call it context — include the facts the model needs to explain, or the output will be confident-sounding guesswork.
“so people understand it”
'People' is doing the widest possible net — developers integrating the API, executives skimming a changelog, and confused support tickets are all 'people,' and they each need a completely different document.
swap: 'people' → '[audience, e.g. developers already using the API who need to update their integration]'
Name who is reading, what they already know, and what they need to do after — it changes every word of the output.
“professional but approachable”
Every piece of writing on earth is asked to be 'professional but approachable' — it's the vanilla of tone instructions, a contradiction that cancels itself out and leaves the model exactly where it started.
swap: 'professional but approachable' → a concrete tone anchor, e.g. 'plain English, no marketing fluff, short sentences, code examples where useful'
Replace mood adjectives with format instructions — tell the model what the output looks like, not how it should feel.
“Write a clear explanation”
'Clear' is grading the output before it exists and telling the model nothing about structure — no length, no sections, no format, no examples. The model will invent a shape and you'll rewrite it anyway.
add: format contract — e.g. '300–400 words, structured as: summary sentence, limit table (endpoint / limit / window), what happens when exceeded, one code snippet showing a 429 response'
Always give the model a format contract: length, sections, and at least one concrete example of what goes in each.
You are writing developer documentation for [audience — e.g. 'backend developers currently integrated with v2 of the API who need to update their code before the new limits go live']. Explain how the new API rate limiting works. Use only the facts below — do not invent limits, codes, or behavior that isn't listed. FACTS TO INCLUDE: - [Rate limit per endpoint or globally — e.g. '100 requests per 60-second rolling window per API key'] - [What happens when the limit is exceeded — e.g. 'HTTP 429 returned with a Retry-After header'] - [Any headers the client can read to track usage — e.g. X-RateLimit-Remaining, X-RateLimit-Reset] - [What changed from the previous limits, if anything] - [Any exceptions or higher-tier limits] FORMAT: - 300–400 words total - Lead with a one-sentence plain-English summary of the limit - Follow with a small table: Endpoint | Limit | Window | On Exceed - Then a short paragraph on how to handle 429s gracefully (exponential backoff, reading the header) - Close with one code snippet showing a 429 response and the Retry-After header - Plain English, short sentences, no marketing language - If a fact is missing from the list above, note it with [NEEDS CONTENT] rather than inventing it
/roast/example/no-audience