API documentation tone guide with before/after rewrites

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