API documentation tone guide with before/after rewrites
Views
5.2K
Copies
1.7K
Likes
835
Comments
0
Copy rate
32.0%
Prompt
You are a technical writer who has shipped docs for Stripe, Twilio, and two YC companies. Write a tone guide for [api_product] documentation aimed at [developer_audience].
Deliver:
- 5 tone principles (short rules)
- Voice attributes (what we sound like / what we don't)
- Reading-level and sentence-length rules
- Structural rules for error messages, code samples, and conceptual pages
- 4 before/after rewrites of real-feeling doc paragraphs
- A glossary of words we prefer vs. words we avoid
- A "when to use humor" section (honest — usually never)
Make it something a new tech writer can onboard from in 30 minutes.Customise this prompt
Fill in 2 variables to personalise this prompt
Preview
You are a technical writer who has shipped docs for Stripe, Twilio, and two YC companies. Write a tone guide for [api_product] documentation aimed at [developer_audience].
Deliver:
- 5 tone principles (short rules)
- Voice attributes (what we sound like / what we don't)
- Reading-level and sentence-length rules
- Structural rules for error messages, code samples, and conceptual pages
- 4 before/after rewrites of real-feeling doc paragraphs
- A glossary of words we prefer vs. words we avoid
- A "when to use humor" section (honest — usually never)
Make it something a new tech writer can onboard from in 30 minutes.
Example output
# API Documentation Tone Guide — Lumenstream Streaming API
**Audience:** Backend engineers at companies with 10-500 developers integrating real-time data feeds.
---
## 5 Tone Principles
1. **Assume the reader is smart, in a hurry, and annoyed at something else.** Not this page. Something else. Help them leave faster.
2. **Lead with the working code.** Explanation comes second. Context comes third.
3. **One job per sentence.** If a sentence does two things, it's two sentences.
4. **Be direct about limits and failure modes.** Developers trust docs that admit what the product can't do.
5. **No marketing voice, ever.** Docs are a separate product with separate readers. A paragraph that sounds like a landing page is a bug.
---
## Voice Attributes
| We sound like | We don't sound like |
|---|---|
| A senior engineer explaining something at a whiteboard | A product manager in a keynote |
| Stripe docs, Django docs, Tailwind docs | A corporate blog, a chatbot, a TED talk |
| Confident about what the API does | Confident about what the API will do someday |
| Specific, measured, dry | Enthusiastic, hype-y, self-congratulatory |
---
## Reading Level & Length
- Target Flesch-Kincaid reading level: Grade 9-10
- Max sentence length: 24 words (hard cap: 32)
- Max paragraph length: 4 sentences
- Use bullets when listing 3+ items
- Code comes within the first 80% of scroll on any reference page
---
## Structural Rules
### Error Messages
Every documented error must include:
- The full error code and HTTP status
- A one-line plain-English description
- One specific cause
- The exact action to fix it
- A link to the relevant concept page
### Code Samples
- Samples must run as-is after copy-paste (no pseudocode in reference docs)
- Show the happy path first, edge cases after
- Include at least two languages: cURL + one SDK
- Comment only where a reader could reasonably be confused
- Never use `foo`, `bar`, `baz` — use domain-realistic names (`stream_id`, `event_payload`)
### Conceptual Pages
- Start with a 1-sentence definition ("What this is")
- Follow with a 2-3 sentence "why it exists" section
- Then a diagram or code example
- End with "When to use this / when not to"
---
## Before / After Rewrites
### Example 1: Landing-page voice in a reference doc
**Before:**
```
Our powerful streaming API empowers developers to build mission-critical
applications with real-time data at unprecedented scale, leveraging
cutting-edge infrastructure for a best-in-class experience.
```
**After:**
```
The Lumenstream API delivers events over a persistent HTTP/2 connection.
It's designed for workloads up to 100,000 events per second per connection.
```
### Example 2: Hedge-y instructions
**Before:**
```
You may want to consider calling the `reconnect()` method if you happen
to experience any issues with the connection, as this could potentially
help resolve the problem in some cases.
```
**After:**
```
Call `reconnect()` when you receive a `connection_dropped` event.
It restores the session in under 400ms and replays missed events from the last checkpoint.
```
### Example 3: Vague error message
**Before:**
```
Error 403: Something went wrong. Please check your credentials and try again.
```
**After:**
```
Error 403 — invalid_scope
The API key exists but does not include the `streams:write` scope.
Fix: regenerate the key at /settings/keys with write scope enabled.
See: Authentication > Scopes.
```
### Example 4: Buried working code
**Before:**
```
In order to successfully create a new stream, you will first need to
understand the lifecycle of a stream object, which is composed of
several distinct phases that we will now walk through in detail.
Once you've read the conceptual overview below, you'll be ready
to try your first request.
```
**After:**
```
Create a stream:
curl https://api.lumenstream.dev/v1/streams \
-H "Authorization: Bearer ${API_KEY}" \
-d '{"name":"checkout_events","retention_hours":24}'
The stream lifecycle (created → active → draining → closed) is described below.
```
---
## Preferred / Avoided Words
| Prefer | Avoid |
|---|---|
| use | leverage, utilize |
| send | fire off, blast |
| create | spin up, stand up |
| returns | yields, surfaces |
| fails | errors out |
| works | functions |
| limit | cap, ceiling |
| required | mandatory |
| optional | nice-to-have |
| in seconds | at lightning speed |
Never: "simply," "just," "easy," "intuitive," "powerful," "seamless."
---
## When to Use Humor
Almost never.
The one acceptable place: 404 pages and Easter egg error states that a developer will only hit if they're deep in debug mode. Even there, keep it under 10 words and never at the reader's expense. If you're unsure, don't.