Voice and Tone Guide
When to Use
- User needs to document their brand voice for a content team
- User asks for tone guidelines, writing style documentation, or brand voice rules
- User wants to standardize how their brand sounds across channels and writers
- User needs a reference document that ensures consistent brand communication
- Do NOT use when the user wants to analyze their audience (use
audience-analysis instead)
- Do NOT use when the user wants to plan content topics and schedules (use
editorial-calendar instead)
- Do NOT use when the user wants to write actual content (use
blog-post-writing instead)
- Do NOT use when the user wants to adjust the tone of existing text (use
tone-adjustment instead)
Process
Collect brand and voice context. Ask the user for:
- Company or brand name and what they do
- Current audience (who reads/hears their content)
- 3-5 adjectives that describe how the brand should sound
- 3-5 adjectives that describe how the brand should NOT sound
- Examples of content they like (their own or competitors')
- Content channels: blog, social media, email, product UI, customer support
Define voice attributes. Establish 3-4 core voice attributes:
- Each attribute is a named quality with a spectrum (e.g., "Confident, not arrogant")
- Each attribute includes a definition specific to this brand
- Each attribute has a "This, not that" pair showing the boundary
- Voice attributes are constant across all channels -- they define who the brand is
Define tone variations. Tone changes by context while voice stays constant:
- Map tone adjustments for different scenarios: celebrating wins, delivering bad news, educating, selling, apologizing
- Map tone adjustments by channel: social media (lighter), email (direct), blog (thorough), support (empathetic)
- For each adjustment, show how the voice attributes manifest differently
Create the vocabulary guide. Build lists of:
- Use these words: Terms that reflect the brand voice (with examples in context)
- Avoid these words: Terms that conflict with the brand voice (with preferred alternatives)
- Industry-specific decisions: Jargon to use, jargon to explain, jargon to avoid
- Formality markers: Contractions (yes/no), first person (I/we), exclamation marks (limit), emoji use
Write do/don't examples. For each voice attribute:
- 2-3 paired examples showing the same message written on-brand and off-brand
- Examples should cover different content types (social post, email, error message, blog intro)
- Each pair should make the distinction obvious without additional explanation
Write platform-specific samples. Create one sample piece for each primary channel:
- Blog post opening paragraph
- Social media post
- Email newsletter opening
- Product notification or error message (if applicable)
- Customer support response (if applicable)
- Each sample demonstrates the voice in action on that specific platform
Build the quick reference card. Distill the guide into a one-page reference that writers can keep open while working.
Output Format
## Voice and Tone Guide: [Brand Name]
**Brand mission (one line):** [What the brand does and for whom]
---
### Voice Attributes
Our voice is constant. It is who we are, regardless of channel or context.
**1. [Attribute 1]: [One-sentence definition]**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]
- Spectrum: [lower end] |----X----| [upper end]
**2. [Attribute 2]: [One-sentence definition]**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]
- Spectrum: [lower end] |----X----| [upper end]
**3. [Attribute 3]: [One-sentence definition]**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]
- Spectrum: [lower end] |----X----| [upper end]
**4. [Attribute 4]: [One-sentence definition] (optional)**
- We are: [specific positive boundary]
- We are NOT: [specific negative boundary]
---
### Tone Adjustments by Context
| Context | Tone Shift | Example |
|---------|-----------|---------|
| Celebrating a win | [how voice attributes adjust] | [sample sentence] |
| Delivering bad news | [how voice attributes adjust] | [sample sentence] |
| Educating/teaching | [how voice attributes adjust] | [sample sentence] |
| Selling/promoting | [how voice attributes adjust] | [sample sentence] |
| Apologizing | [how voice attributes adjust] | [sample sentence] |
### Tone Adjustments by Channel
| Channel | Tone Notes | Formality Level |
|---------|-----------|----------------|
| Blog | [adjustments] | [level] |
| Social media | [adjustments] | [level] |
| Email | [adjustments] | [level] |
| Product UI | [adjustments] | [level] |
| Support | [adjustments] | [level] |
---
### Vocabulary Guide
**Use These Words:**
| Word/Phrase | In Context |
|-------------|-----------|
| [word] | [example sentence using this word] |
| [word] | [example sentence] |
**Avoid These Words:**
| Avoid | Use Instead | Why |
|-------|------------|-----|
| [word] | [alternative] | [reason] |
| [word] | [alternative] | [reason] |
**Formality Decisions:**
| Element | Decision |
|---------|---------|
| Contractions | [yes/no/context-dependent] |
| First person | [I / we / they / context-dependent] |
| Exclamation marks | [limit per piece] |
| Emoji | [never / sparingly / platform-specific] |
| Oxford comma | [yes / no] |
---
### Do/Don't Examples
**Attribute 1: [Name]**
| Do (On-Brand) | Don't (Off-Brand) |
|--------------|-------------------|
| [on-brand version of message] | [off-brand version of same message] |
| [on-brand version] | [off-brand version] |
**Attribute 2: [Name]**
| Do (On-Brand) | Don't (Off-Brand) |
|--------------|-------------------|
| [on-brand version] | [off-brand version] |
| [on-brand version] | [off-brand version] |
---
### Platform Samples
**Blog Post Opening:**
[Sample opening paragraph demonstrating the voice on the blog]
**Social Media Post:**
[Sample post demonstrating the voice on social]
**Email Newsletter Opening:**
[Sample newsletter opening demonstrating the voice in email]
**Error Message / Notification:**
[Sample product message demonstrating the voice in UI]
---
### Quick Reference Card
| Attribute | We Are | We Are Not |
|-----------|--------|-----------|
| [1] | [positive] | [negative] |
| [2] | [positive] | [negative] |
| [3] | [positive] | [negative] |
**Before you publish, check:**
- [ ] Does this sound like [brand name], or could any company have written it?
- [ ] Would [persona name] trust this and act on it?
- [ ] Is every claim specific and supported?
- [ ] Does the tone match the context (celebrating/teaching/selling/apologizing)?
Rules
- NEVER define voice attributes as single adjectives without boundaries -- "friendly" means nothing without "friendly, not childish" or "friendly, not artificially cheerful"
- NEVER use more than 4 voice attributes -- more than 4 creates paralysis for writers trying to embody all of them simultaneously
- NEVER skip the do/don't examples -- abstract voice descriptions become concrete only through paired examples
- NEVER write a voice guide without platform-specific samples -- the same voice sounds different on Twitter than in a support email
- NEVER conflate voice and tone -- voice is constant (who we are), tone varies by context (how we adapt)
- ALWAYS provide a "This, not that" boundary for every voice attribute
- ALWAYS include at least 2 do/don't paired examples per voice attribute
- ALWAYS include a vocabulary guide with specific words to use and avoid
- ALWAYS provide platform-specific writing samples showing the voice in action
- ALWAYS include a quick reference card that fits on one page
- Voice attributes should be specific to this brand, not generic ("We are confident" applies to every brand; "We explain complex things without condescension" is specific)
- The guide should be usable by a new writer on day one -- if they cannot produce on-brand content using only this document, it is incomplete
Edge Cases
- User has no existing brand voice. Help them discover it by asking: "If your brand were a person at a dinner party, how would they talk?" and "Show me 3 pieces of content you wish you had written." Build the voice from their answers and aspirations.
- User's current voice is inconsistent across channels. Audit the inconsistencies first. Ask which channel's voice feels most authentic, and build the guide around that anchor. The guide becomes the tool for aligning the other channels.
- Brand serves audiences with very different expectations (e.g., consumers and enterprises). Create one core voice with distinct tone profiles for each audience segment. The voice stays the same; the tone adjustments section gets more detailed.
- User has a strong founder voice that the team needs to replicate. Analyze the founder's writing for patterns: sentence length, vocabulary, punctuation habits, recurring structural choices. Document these as voice attributes, not as "write like [founder name]."
- User is rebranding. Document both the old voice (what to move away from) and the new voice (what to move toward). Include a transition guide that shows the shift for each attribute.
Example
Input: "Create a voice and tone guide for our developer tools company. We make an API monitoring platform. Our audience is software engineers and DevOps teams. We want to sound technically credible but not dry. We admire how Stripe communicates."
Output:
Voice and Tone Guide: PulseAPI
Brand mission (one line): PulseAPI helps engineering teams catch API failures before their users do.
Voice Attributes
Our voice is constant. It is who we are, regardless of channel or context.
1. Technically Precise: We use correct terminology and show our work.
- We are: accurate, specific, and unafraid of technical depth
- We are NOT: dumbed-down, vague, or handwavy about technical details
- Spectrum: Oversimplified |--------X--| Academic
2. Direct: We say what we mean in the fewest words possible.
- We are: concise, action-oriented, and clear about what to do next
- We are NOT: wordy, hedge-filled, or buried in qualifications
- Spectrum: Terse |------X----| Verbose
3. Calm Under Pressure: We communicate urgency without panic.
- We are: composed, solution-focused, and steady in incident communication
- We are NOT: alarming, dismissive ("no big deal"), or overly apologetic
- Spectrum: Dismissive |--------X--| Panicked
4. Respectful of the Reader's Time: We front-load value.
- We are: structured, scannable, and immediately useful
- We are NOT: padded, repetitive, or forcing readers to dig for the answer
- Spectrum: Incomplete |------X----| Exhaustive
Tone Adjustments by Context
| Context |
Tone Shift |
Example |
| Celebrating a win |
Proud but factual -- lead with the achievement, not the emotion |
"PulseAPI now monitors 2 billion API calls per day. Here is what we built to get there." |
| Delivering bad news (incident) |
Calm, specific, solution-first |
"API monitoring delayed by 3 minutes between 14:02-14:15 UTC. Root cause identified. All alerts are current." |
| Educating/teaching |
Patient but not patronizing -- assume the reader is smart |
"Rate limiting prevents one client from consuming all available capacity. Here is how to implement it." |
| Selling/promoting |
Feature-first, outcome-clear -- show, do not claim |
"Set up alerts in 4 lines of code. Get notified before your users notice." |
| Apologizing |
Take responsibility, state impact, describe fix |
"We made a mistake in the billing calculation for March. Here is what happened, who is affected, and what we have done." |
Tone Adjustments by Channel
| Channel |
Tone Notes |
Formality Level |
| Blog |
Thorough, educational, code examples welcome |
Medium-formal |
| Twitter/X |
Punchy, technical one-liners, occasional dry humor |
Casual |
| Email |
Direct, action-oriented, structured with headers |
Medium-formal |
| Product UI |
Minimal, instructive, no personality flourishes |
Formal |
| Docs |
Reference-style, scannable, example-heavy |
Formal |
Vocabulary Guide
Use These Words:
| Word/Phrase |
In Context |
| "Monitor" |
"Monitor your API endpoints in real time" |
| "Alert" |
"Set up alerts for latency spikes above 500ms" |
| "Incident" |
"During the incident, response times exceeded SLA thresholds" |
| "Deploy" |
"Deploy the monitoring agent with one command" |
Avoid These Words:
| Avoid |
Use Instead |
Why |
| "Solution" |
"Tool" or "platform" or the specific feature name |
Vague sales language that engineers distrust |
| "Leverage" |
"Use" |
Corporate jargon -- say what you mean |
| "Seamless" |
Describe the specific integration steps |
Every product claims to be seamless; none of them are |
| "Cutting-edge" |
Describe the specific technical capability |
Meaningless superlative that signals marketing over substance |
| "Empower" |
State what the user can now do |
Patronizing and vague |
Formality Decisions:
| Element |
Decision |
| Contractions |
Yes -- "you'll," "we're," "it's" are natural in technical writing |
| First person |
"We" for PulseAPI, "you" for the reader. Never "one" or "the user." |
| Exclamation marks |
Maximum 1 per blog post, 0 in docs, 0 in incident communication |
| Emoji |
Never in product UI or docs. Sparingly on social (max 1 per post). |
| Oxford comma |
Yes, always |
Do/Don't Examples
Attribute: Technically Precise
| Do (On-Brand) |
Don't (Off-Brand) |
| "PulseAPI checks endpoint health every 30 seconds and alerts you when p99 latency exceeds your defined threshold." |
"PulseAPI keeps an eye on your APIs and lets you know if something seems off." |
| "The agent requires 12MB of memory and adds less than 2ms of latency per request." |
"The agent is lightweight and has minimal impact on performance." |
Attribute: Direct
| Do (On-Brand) |
Don't (Off-Brand) |
| "Add the SDK. Set your thresholds. Deploy." |
"Getting started with PulseAPI is a straightforward process that begins with adding our easy-to-use SDK to your application." |
| "Your API returned 503 errors 47 times in the last hour." |
"It appears that there may be some issues with your API availability that you might want to look into." |
Platform Samples
Blog Post Opening:
Every API has a failure budget. The question is whether you are spending it intentionally or discovering the overdraft from a customer complaint. PulseAPI's latency distribution analysis shows that 73% of API incidents are preceded by a p95 latency increase 10-15 minutes before the first error. Here is how to catch that signal.
Social Media Post (Twitter/X):
Your API responded 200 OK but took 4 seconds.
Your monitoring says everything is fine.
Your users say nothing -- they already left.
p99 latency matters more than status codes.
Email Newsletter Opening:
Three changes in this release: custom alerting windows, Slack thread integration for incident timelines, and a 40% reduction in false positive alerts. Here is what each one does and why we built it.
Error Message (Product UI):
Alert configuration saved. Monitoring starts within 60 seconds.
Quick Reference Card
| Attribute |
We Are |
We Are Not |
| Technically Precise |
Specific, accurate, depth-first |
Vague, dumbed-down, imprecise |
| Direct |
Concise, action-oriented, clear |
Wordy, hedging, buried |
| Calm Under Pressure |
Composed, solution-focused |
Alarming, dismissive, over-apologetic |
| Time-Respectful |
Structured, scannable, front-loaded |
Padded, repetitive, meandering |
Before you publish, check:
1---2name: voice-tone-guide3description: Creates brand voice and tone documentation with do/don't examples, vocabulary lists, platform-specific modifiers, and writing samples that any writer can follow to produce on-brand content. Use when the user needs to document their brand voice, create tone guidelines, build a writing style guide, or standardize how their brand communicates. Do NOT use for audience analysis (use `audience-analysis`), content strategy planning (use `editorial-calendar`), or actual content writing (use `blog-post-writing`).4license: Apache-2.05---67# Voice and Tone Guide89## When to Use1011- User needs to document their brand voice for a content team12- User asks for tone guidelines, writing style documentation, or brand voice rules13- User wants to standardize how their brand sounds across channels and writers14- User needs a reference document that ensures consistent brand communication15- Do NOT use when the user wants to analyze their audience (use `audience-analysis` instead)16- Do NOT use when the user wants to plan content topics and schedules (use `editorial-calendar` instead)17- Do NOT use when the user wants to write actual content (use `blog-post-writing` instead)18- Do NOT use when the user wants to adjust the tone of existing text (use `tone-adjustment` instead)1920## Process21221. **Collect brand and voice context.** Ask the user for:23 - Company or brand name and what they do24 - Current audience (who reads/hears their content)25 - 3-5 adjectives that describe how the brand should sound26 - 3-5 adjectives that describe how the brand should NOT sound27 - Examples of content they like (their own or competitors')28 - Content channels: blog, social media, email, product UI, customer support29302. **Define voice attributes.** Establish 3-4 core voice attributes:31 - Each attribute is a named quality with a spectrum (e.g., "Confident, not arrogant")32 - Each attribute includes a definition specific to this brand33 - Each attribute has a "This, not that" pair showing the boundary34 - Voice attributes are constant across all channels -- they define who the brand is35363. **Define tone variations.** Tone changes by context while voice stays constant:37 - Map tone adjustments for different scenarios: celebrating wins, delivering bad news, educating, selling, apologizing38 - Map tone adjustments by channel: social media (lighter), email (direct), blog (thorough), support (empathetic)39 - For each adjustment, show how the voice attributes manifest differently40414. **Create the vocabulary guide.** Build lists of:42 - **Use these words:** Terms that reflect the brand voice (with examples in context)43 - **Avoid these words:** Terms that conflict with the brand voice (with preferred alternatives)44 - **Industry-specific decisions:** Jargon to use, jargon to explain, jargon to avoid45 - **Formality markers:** Contractions (yes/no), first person (I/we), exclamation marks (limit), emoji use46475. **Write do/don't examples.** For each voice attribute:48 - 2-3 paired examples showing the same message written on-brand and off-brand49 - Examples should cover different content types (social post, email, error message, blog intro)50 - Each pair should make the distinction obvious without additional explanation51526. **Write platform-specific samples.** Create one sample piece for each primary channel:53 - Blog post opening paragraph54 - Social media post55 - Email newsletter opening56 - Product notification or error message (if applicable)57 - Customer support response (if applicable)58 - Each sample demonstrates the voice in action on that specific platform59607. **Build the quick reference card.** Distill the guide into a one-page reference that writers can keep open while working.6162## Output Format6364```65## Voice and Tone Guide: [Brand Name]6667**Brand mission (one line):** [What the brand does and for whom]6869---7071### Voice Attributes7273Our voice is constant. It is who we are, regardless of channel or context.7475**1. [Attribute 1]: [One-sentence definition]**76- We are: [specific positive boundary]77- We are NOT: [specific negative boundary]78- Spectrum: [lower end] |----X----| [upper end]7980**2. [Attribute 2]: [One-sentence definition]**81- We are: [specific positive boundary]82- We are NOT: [specific negative boundary]83- Spectrum: [lower end] |----X----| [upper end]8485**3. [Attribute 3]: [One-sentence definition]**86- We are: [specific positive boundary]87- We are NOT: [specific negative boundary]88- Spectrum: [lower end] |----X----| [upper end]8990**4. [Attribute 4]: [One-sentence definition] (optional)**91- We are: [specific positive boundary]92- We are NOT: [specific negative boundary]9394---9596### Tone Adjustments by Context9798| Context | Tone Shift | Example |99|---------|-----------|---------|100| Celebrating a win | [how voice attributes adjust] | [sample sentence] |101| Delivering bad news | [how voice attributes adjust] | [sample sentence] |102| Educating/teaching | [how voice attributes adjust] | [sample sentence] |103| Selling/promoting | [how voice attributes adjust] | [sample sentence] |104| Apologizing | [how voice attributes adjust] | [sample sentence] |105106### Tone Adjustments by Channel107108| Channel | Tone Notes | Formality Level |109|---------|-----------|----------------|110| Blog | [adjustments] | [level] |111| Social media | [adjustments] | [level] |112| Email | [adjustments] | [level] |113| Product UI | [adjustments] | [level] |114| Support | [adjustments] | [level] |115116---117118### Vocabulary Guide119120**Use These Words:**121| Word/Phrase | In Context |122|-------------|-----------|123| [word] | [example sentence using this word] |124| [word] | [example sentence] |125126**Avoid These Words:**127| Avoid | Use Instead | Why |128|-------|------------|-----|129| [word] | [alternative] | [reason] |130| [word] | [alternative] | [reason] |131132**Formality Decisions:**133| Element | Decision |134|---------|---------|135| Contractions | [yes/no/context-dependent] |136| First person | [I / we / they / context-dependent] |137| Exclamation marks | [limit per piece] |138| Emoji | [never / sparingly / platform-specific] |139| Oxford comma | [yes / no] |140141---142143### Do/Don't Examples144145**Attribute 1: [Name]**146147| Do (On-Brand) | Don't (Off-Brand) |148|--------------|-------------------|149| [on-brand version of message] | [off-brand version of same message] |150| [on-brand version] | [off-brand version] |151152**Attribute 2: [Name]**153154| Do (On-Brand) | Don't (Off-Brand) |155|--------------|-------------------|156| [on-brand version] | [off-brand version] |157| [on-brand version] | [off-brand version] |158159---160161### Platform Samples162163**Blog Post Opening:**164[Sample opening paragraph demonstrating the voice on the blog]165166**Social Media Post:**167[Sample post demonstrating the voice on social]168169**Email Newsletter Opening:**170[Sample newsletter opening demonstrating the voice in email]171172**Error Message / Notification:**173[Sample product message demonstrating the voice in UI]174175---176177### Quick Reference Card178179| Attribute | We Are | We Are Not |180|-----------|--------|-----------|181| [1] | [positive] | [negative] |182| [2] | [positive] | [negative] |183| [3] | [positive] | [negative] |184185**Before you publish, check:**186- [ ] Does this sound like [brand name], or could any company have written it?187- [ ] Would [persona name] trust this and act on it?188- [ ] Is every claim specific and supported?189- [ ] Does the tone match the context (celebrating/teaching/selling/apologizing)?190```191192## Rules1931941. NEVER define voice attributes as single adjectives without boundaries -- "friendly" means nothing without "friendly, not childish" or "friendly, not artificially cheerful"1952. NEVER use more than 4 voice attributes -- more than 4 creates paralysis for writers trying to embody all of them simultaneously1963. NEVER skip the do/don't examples -- abstract voice descriptions become concrete only through paired examples1974. NEVER write a voice guide without platform-specific samples -- the same voice sounds different on Twitter than in a support email1985. NEVER conflate voice and tone -- voice is constant (who we are), tone varies by context (how we adapt)1996. ALWAYS provide a "This, not that" boundary for every voice attribute2007. ALWAYS include at least 2 do/don't paired examples per voice attribute2018. ALWAYS include a vocabulary guide with specific words to use and avoid2029. ALWAYS provide platform-specific writing samples showing the voice in action20310. ALWAYS include a quick reference card that fits on one page20411. Voice attributes should be specific to this brand, not generic ("We are confident" applies to every brand; "We explain complex things without condescension" is specific)20512. The guide should be usable by a new writer on day one -- if they cannot produce on-brand content using only this document, it is incomplete206207## Edge Cases208209- **User has no existing brand voice.** Help them discover it by asking: "If your brand were a person at a dinner party, how would they talk?" and "Show me 3 pieces of content you wish you had written." Build the voice from their answers and aspirations.210- **User's current voice is inconsistent across channels.** Audit the inconsistencies first. Ask which channel's voice feels most authentic, and build the guide around that anchor. The guide becomes the tool for aligning the other channels.211- **Brand serves audiences with very different expectations (e.g., consumers and enterprises).** Create one core voice with distinct tone profiles for each audience segment. The voice stays the same; the tone adjustments section gets more detailed.212- **User has a strong founder voice that the team needs to replicate.** Analyze the founder's writing for patterns: sentence length, vocabulary, punctuation habits, recurring structural choices. Document these as voice attributes, not as "write like [founder name]."213- **User is rebranding.** Document both the old voice (what to move away from) and the new voice (what to move toward). Include a transition guide that shows the shift for each attribute.214215## Example216217**Input:** "Create a voice and tone guide for our developer tools company. We make an API monitoring platform. Our audience is software engineers and DevOps teams. We want to sound technically credible but not dry. We admire how Stripe communicates."218219**Output:**220221## Voice and Tone Guide: PulseAPI222223**Brand mission (one line):** PulseAPI helps engineering teams catch API failures before their users do.224225---226227### Voice Attributes228229Our voice is constant. It is who we are, regardless of channel or context.230231**1. Technically Precise: We use correct terminology and show our work.**232- We are: accurate, specific, and unafraid of technical depth233- We are NOT: dumbed-down, vague, or handwavy about technical details234- Spectrum: Oversimplified |--------X--| Academic235236**2. Direct: We say what we mean in the fewest words possible.**237- We are: concise, action-oriented, and clear about what to do next238- We are NOT: wordy, hedge-filled, or buried in qualifications239- Spectrum: Terse |------X----| Verbose240241**3. Calm Under Pressure: We communicate urgency without panic.**242- We are: composed, solution-focused, and steady in incident communication243- We are NOT: alarming, dismissive ("no big deal"), or overly apologetic244- Spectrum: Dismissive |--------X--| Panicked245246**4. Respectful of the Reader's Time: We front-load value.**247- We are: structured, scannable, and immediately useful248- We are NOT: padded, repetitive, or forcing readers to dig for the answer249- Spectrum: Incomplete |------X----| Exhaustive250251---252253### Tone Adjustments by Context254255| Context | Tone Shift | Example |256|---------|-----------|---------|257| Celebrating a win | Proud but factual -- lead with the achievement, not the emotion | "PulseAPI now monitors 2 billion API calls per day. Here is what we built to get there." |258| Delivering bad news (incident) | Calm, specific, solution-first | "API monitoring delayed by 3 minutes between 14:02-14:15 UTC. Root cause identified. All alerts are current." |259| Educating/teaching | Patient but not patronizing -- assume the reader is smart | "Rate limiting prevents one client from consuming all available capacity. Here is how to implement it." |260| Selling/promoting | Feature-first, outcome-clear -- show, do not claim | "Set up alerts in 4 lines of code. Get notified before your users notice." |261| Apologizing | Take responsibility, state impact, describe fix | "We made a mistake in the billing calculation for March. Here is what happened, who is affected, and what we have done." |262263### Tone Adjustments by Channel264265| Channel | Tone Notes | Formality Level |266|---------|-----------|----------------|267| Blog | Thorough, educational, code examples welcome | Medium-formal |268| Twitter/X | Punchy, technical one-liners, occasional dry humor | Casual |269| Email | Direct, action-oriented, structured with headers | Medium-formal |270| Product UI | Minimal, instructive, no personality flourishes | Formal |271| Docs | Reference-style, scannable, example-heavy | Formal |272273---274275### Vocabulary Guide276277**Use These Words:**278| Word/Phrase | In Context |279|-------------|-----------|280| "Monitor" | "Monitor your API endpoints in real time" |281| "Alert" | "Set up alerts for latency spikes above 500ms" |282| "Incident" | "During the incident, response times exceeded SLA thresholds" |283| "Deploy" | "Deploy the monitoring agent with one command" |284285**Avoid These Words:**286| Avoid | Use Instead | Why |287|-------|------------|-----|288| "Solution" | "Tool" or "platform" or the specific feature name | Vague sales language that engineers distrust |289| "Leverage" | "Use" | Corporate jargon -- say what you mean |290| "Seamless" | Describe the specific integration steps | Every product claims to be seamless; none of them are |291| "Cutting-edge" | Describe the specific technical capability | Meaningless superlative that signals marketing over substance |292| "Empower" | State what the user can now do | Patronizing and vague |293294**Formality Decisions:**295| Element | Decision |296|---------|---------|297| Contractions | Yes -- "you'll," "we're," "it's" are natural in technical writing |298| First person | "We" for PulseAPI, "you" for the reader. Never "one" or "the user." |299| Exclamation marks | Maximum 1 per blog post, 0 in docs, 0 in incident communication |300| Emoji | Never in product UI or docs. Sparingly on social (max 1 per post). |301| Oxford comma | Yes, always |302303---304305### Do/Don't Examples306307**Attribute: Technically Precise**308309| Do (On-Brand) | Don't (Off-Brand) |310|--------------|-------------------|311| "PulseAPI checks endpoint health every 30 seconds and alerts you when p99 latency exceeds your defined threshold." | "PulseAPI keeps an eye on your APIs and lets you know if something seems off." |312| "The agent requires 12MB of memory and adds less than 2ms of latency per request." | "The agent is lightweight and has minimal impact on performance." |313314**Attribute: Direct**315316| Do (On-Brand) | Don't (Off-Brand) |317|--------------|-------------------|318| "Add the SDK. Set your thresholds. Deploy." | "Getting started with PulseAPI is a straightforward process that begins with adding our easy-to-use SDK to your application." |319| "Your API returned 503 errors 47 times in the last hour." | "It appears that there may be some issues with your API availability that you might want to look into." |320321---322323### Platform Samples324325**Blog Post Opening:**326Every API has a failure budget. The question is whether you are spending it intentionally or discovering the overdraft from a customer complaint. PulseAPI's latency distribution analysis shows that 73% of API incidents are preceded by a p95 latency increase 10-15 minutes before the first error. Here is how to catch that signal.327328**Social Media Post (Twitter/X):**329Your API responded 200 OK but took 4 seconds.330331Your monitoring says everything is fine.332333Your users say nothing -- they already left.334335p99 latency matters more than status codes.336337**Email Newsletter Opening:**338Three changes in this release: custom alerting windows, Slack thread integration for incident timelines, and a 40% reduction in false positive alerts. Here is what each one does and why we built it.339340**Error Message (Product UI):**341Alert configuration saved. Monitoring starts within 60 seconds.342343---344345### Quick Reference Card346347| Attribute | We Are | We Are Not |348|-----------|--------|-----------|349| Technically Precise | Specific, accurate, depth-first | Vague, dumbed-down, imprecise |350| Direct | Concise, action-oriented, clear | Wordy, hedging, buried |351| Calm Under Pressure | Composed, solution-focused | Alarming, dismissive, over-apologetic |352| Time-Respectful | Structured, scannable, front-loaded | Padded, repetitive, meandering |353354**Before you publish, check:**355- [ ] Does this sound like it was written by an engineer for engineers?356- [ ] Could a developer act on this content without asking follow-up questions?357- [ ] Is every claim specific and supported with numbers or examples?358- [ ] Does the tone match the context (teaching/announcing/resolving)?
FerroxLabs