gh-jamesrochabrun-skills/skills/content-brief-generator/references/tone_voice_guide.md

# Tone & Voice Guide

Complete guide to developing and maintaining consistent voice and tone in your content.

---

## Voice vs. Tone

### Voice
**Your brand's personality** - consistent across all content

**Think of it as:**
- Who you are as a brand
- Your character
- Never changes

**Examples:**
- Mailchimp: "Friendly, helpful, human"
- Stripe: "Direct, technical, trustworthy"
- Nike: "Inspirational, motivational, bold"

### Tone
**How voice adapts** to context - changes based on situation

**Think of it as:**
- Your emotional state
- How you say something
- Varies by context

**Examples:**
- **Error message:** Apologetic, helpful
- **Success message:** Congratulatory, encouraging
- **Technical docs:** Professional, precise
- **Marketing:** Enthusiastic, persuasive

**Analogy:**
Voice = Your personality
Tone = Your mood

---

## Defining Your Voice

### Voice Attributes Framework

Choose 3-4 core attributes that define your brand voice:

**The Spectrum:**

```
Formal ←────────────→ Casual
Serious ←────────────→ Funny
Respectful ←────────────→ Irreverent
Enthusiastic ←────────────→ Matter-of-fact
Traditional ←────────────→ Innovative
```

### Example Voice Definitions

**Mailchimp:**
- Friendly but not silly
- Clever but not overly witty
- Helpful but not overbearing
- Expert but not bossy

**Slack:**
- Professional but approachable
- Technical but not intimidating
- Playful but not childish
- Direct but not cold

**Atlassian:**
- Straightforward and honest
- Enthusiastically professional
- Conversational yet informative
- Smart but not condescending

---

## Voice Dimensions

### 1. Formality

**Formal:**
- Professional language
- Complete sentences
- No contractions
- Third person

**Example:**
"The application has been successfully deployed to the production environment."

**Casual:**
- Conversational language
- Contractions okay
- First/second person
- Shorter sentences

**Example:**
"You're all set! Your app is live."

**When to use:**
- Formal: Legal, compliance, enterprise docs
- Casual: Blogs, social media, onboarding

---

### 2. Enthusiasm

**Highly Enthusiastic:**
- Exclamation points
- Superlatives (amazing, incredible)
- Energy and excitement
- Emojis (in appropriate contexts)

**Example:**
"This is amazing! You just saved 10 hours of work. Let's celebrate! 🎉"

**Neutral/Matter-of-fact:**
- Period instead of exclamation
- Factual statements
- No hyperbole
- Professional tone

**Example:**
"The task has been completed successfully. You saved 10 hours."

**When to use:**
- Enthusiastic: Consumer products, celebrations, achievements
- Neutral: Technical docs, business content, data reports

---

### 3. Technical Level

**Highly Technical:**
- Industry jargon
- Assumes expert knowledge
- Technical accuracy paramount
- Detailed specifications

**Example:**
"The WebSocket connection establishes a persistent, full-duplex communication channel over a single TCP connection."

**Accessible:**
- Plain language
- Explain jargon
- Analogies and examples
- Beginner-friendly

**Example:**
"WebSockets let your app and server talk back and forth in real-time, like a phone call instead of sending letters."

**When to use:**
- Technical: API docs, developer tools, architecture guides
- Accessible: Getting started guides, general audience, marketing

---

### 4. Humor

**Funny/Playful:**
- Jokes and puns
- Pop culture references
- Light-hearted
- Personality shines

**Example:**
"Oops! Looks like something went wrong. Our bad. We're on it faster than you can say 'Have you tried turning it off and on again?'"

**Serious:**
- Professional
- No jokes
- Straightforward
- Business-like

**Example:**
"An error has occurred. Our team has been notified and is working to resolve the issue."

**When to use:**
- Playful: Consumer brands, creative industries, social media
- Serious: Financial services, healthcare, legal, critical errors

---

## Writing in Your Voice

### Voice Checklist

For every piece of content, ask:

- [ ] **Does this sound like us?** (matches voice attributes)
- [ ] **Is it consistent** with previous content?
- [ ] **Would our audience recognize us** without our logo?
- [ ] **Does it feel authentic** or forced?

### Voice Examples by Sentence

**Same content, different voices:**

**Topic: User made an error**

**Mailchimp (friendly, helpful):**
"Oops! It looks like that email address isn't quite right. Try checking for typos?"

**Stripe (direct, technical):**
"Invalid email format. Use format: user@example.com"

**Innocent (playful, quirky):**
"That email address looks a bit wonky. Give it another go?"

**IBM (formal, professional):**
"The email address entered is invalid. Please verify and try again."

---

## Adapting Tone

### Tone Guidelines by Context

| Context | Tone | Example |
|---------|------|---------|
| **Error message** | Apologetic, helpful | "Sorry about that! Here's how to fix it..." |
| **Success** | Encouraging | "Nice work! You're all set." |
| **Warning** | Urgent but calm | "Action required: Your payment failed." |
| **Education** | Patient, clear | "Let's walk through this together." |
| **Marketing** | Persuasive, exciting | "Transform your workflow in minutes!" |
| **Legal** | Formal, precise | "By continuing, you agree to the terms." |
| **Support** | Empathetic, solution-focused | "I understand this is frustrating. Let's solve it." |

---

## Person & Perspective

### First Person (We, Our)

**When to use:**
- Brand speaking
- Company announcements
- Team perspective

**Example:**
"We're excited to announce our new feature. We built this based on your feedback."

**Pros:**
- Personal connection
- Shows team behind brand
- Takes ownership

**Cons:**
- Can feel self-focused
- Less about user

---

### Second Person (You, Your)

**When to use:**
- Most common
- User instructions
- Direct communication
- Marketing copy

**Example:**
"You can now collaborate in real-time. Your team will love it."

**Pros:**
- User-focused
- Clear and direct
- Creates connection

**Cons:**
- Can feel pushy if overused

---

### Third Person (They, User, Customer)

**When to use:**
- Documentation
- Objective content
- Case studies about others

**Example:**
"The user navigates to settings. The system validates their credentials."

**Pros:**
- Professional
- Objective
- Clear for documentation

**Cons:**
- Less personal
- Can feel distant

---

## Active vs. Passive Voice

### Active Voice (Preferred)

**Structure:** Subject performs action

**Examples:**
- "You can deploy your app in minutes."
- "The system processes your request."
- "Click the button to continue."

**Why use:**
- Clearer
- More direct
- Easier to read
- Stronger

---

### Passive Voice (Avoid Usually)

**Structure:** Action performed on subject

**Examples:**
- "Your app can be deployed in minutes."
- "Your request is processed by the system."
- "The button should be clicked to continue."

**When to use:**
- Actor unknown: "The server was restarted."
- Actor irrelevant: "The file was deleted."
- Soften message: "An error was encountered."

---

## Sentence Structure

### Short Sentences
- Easy to read
- Scannable
- Mobile-friendly
- Clear

**Example:**
"Deploy your app fast. No config needed. It just works."

**When to use:**
- Headlines
- Key points
- Mobile content
- Emphasis

---

### Varied Length
- More natural
- Maintains interest
- Provides rhythm

**Example:**
"Deploy your app fast. No configuration needed, no complicated setup process, no hours wasted on devops. It just works."

**When to use:**
- Blog posts
- Long-form content
- Storytelling

---

## Word Choice

### Simple vs. Complex

**Prefer simple:**
- Use vs. utilize
- Help vs. assist
- Buy vs. purchase
- Start vs. commence
- Show vs. demonstrate

**Exception:** Technical accuracy requires specific terms

---

### Positive vs. Negative

**Positive framing (preferred):**
- "Remember your password"
- "Include your address"
- "Make sure to save"

**Negative framing (avoid):**
- "Don't forget your password"
- "Don't leave out your address"
- "Don't lose your work"

---

### Concrete vs. Abstract

**Concrete (preferred):**
- "Save 10 hours per week"
- "Deploy in 5 minutes"
- "99.9% uptime"

**Abstract (avoid):**
- "Save time"
- "Fast deployment"
- "Reliable service"

---

## Common Writing Guidelines

### Contractions

**Use them for conversational tone:**
- Don't vs. Do not
- You're vs. You are
- We've vs. We have

**Skip them for:**
- Legal content
- Very formal contexts
- When emphasis needed: "Do not delete this"

---

### Exclamation Points

**Use sparingly:**
- Celebrations and achievements
- Very exciting news
- Strong emphasis

**Limit to:**
- Once per paragraph max
- Never multiple (!!!)
- Not in B2B formal content

---

### Emojis

**When appropriate:**
- Consumer brands
- Casual social media
- Internal communications
- In-app celebrations

**Avoid in:**
- Enterprise B2B
- Documentation
- Legal/compliance
- Serious topics

---

## Brand Voice Examples

### Technology/Developer Tools

**Stripe:**
- **Voice:** Direct, technical, trustworthy
- **Example:** "Accept payments in minutes. Get started with a few lines of code."
- **Why it works:** Developers want clarity and speed

**Vercel:**
- **Voice:** Modern, enthusiastic, technical
- **Example:** "Deploy your Next.js app. It's crazy fast."
- **Why it works:** Balances technical and excitement

**Twilio:**
- **Voice:** Friendly, technical, empowering
- **Example:** "Build the future of communications. We make it simple."
- **Why it works:** Technical but approachable

---

### Consumer Products

**Mailchimp:**
- **Voice:** Friendly, helpful, sometimes quirky
- **Example:** "That email looks a bit wonky. Want to check it?"
- **Why it works:** Makes tedious tasks feel human

**Slack:**
- **Voice:** Professional-casual, helpful, clear
- **Example:** "Work, simplified. Your team will thank you."
- **Why it works:** Professional without being stuffy

**Headspace:**
- **Voice:** Calm, supportive, encouraging
- **Example:** "Take a moment for yourself. You deserve it."
- **Why it works:** Matches meditation/wellness mission

---

### Enterprise/B2B

**Salesforce:**
- **Voice:** Professional, empowering, visionary
- **Example:** "Transform your business. Connect with customers in a whole new way."
- **Why it works:** Aspirational but credible

**Atlassian:**
- **Voice:** Straightforward, enthusiastic, smart
- **Example:** "Teamwork doesn't have to be hard. Let's make it easier."
- **Why it works:** Acknowledges real problems, offers solutions

---

## Developing Your Voice

### Step 1: Define Core Attributes

Choose 3-4 from these dimensions:

**Formality:**
- Formal, professional, casual, conversational

**Humor:**
- Serious, playful, witty, irreverent

**Enthusiasm:**
- Energetic, neutral, understated

**Technical:**
- Expert, accessible, simple

**Empathy:**
- Warm, neutral, distant

---

### Step 2: Create Voice Chart

| Attribute | We are | We are not | Example |
|-----------|---------|------------|---------|
| Professional | Clear and helpful | Stuffy or robotic | "Here's how to..." not "One must..." |
| Friendly | Warm and welcoming | Overly casual | "Welcome!" not "Sup!" |
| Technical | Accurate and precise | Jargon-heavy | Explain terms first time |

---

### Step 3: Write Examples

For each voice attribute, write before/after examples:

**Before (generic):**
"Our platform provides solutions for your business needs."

**After (our voice - direct, technical, helpful):**
"Deploy your apps faster with built-in CI/CD and automatic scaling."

---

### Step 4: Create Voice Guidelines

Document:
- [ ] Core voice attributes (3-4)
- [ ] Do's and don'ts
- [ ] Example sentences
- [ ] Tone by context
- [ ] Word choice preferences
- [ ] Grammar rules (contractions, etc.)

---

## Testing Your Voice

### Voice Consistency Check

1. **Remove branding** from 5 pieces of content
2. **Mix with competitors'** content
3. **Can people identify yours?**

If yes → Voice is distinctive
If no → Need stronger voice

---

### Reader Feedback

Ask your audience:
- How would you describe our voice?
- Does it match your expectations?
- What do you like/dislike?

---

## Maintaining Voice

### Team Alignment

**Onboarding:**
- Share voice guidelines
- Review examples
- Practice exercises

**Review Process:**
- Check content against voice guidelines
- Provide specific feedback
- Create a voice champion

**Documentation:**
- Voice guidelines in shared doc
- Examples library
- Regular updates

---

### Voice Evolution

**When to evolve:**
- Rebranding
- New audience
- Company maturity
- Market shift

**How to evolve:**
- Document changes
- Transition gradually
- Update guidelines
- Train team

**What to keep:**
- Core personality
- Brand values
- Recognition

---

## Voice Guidelines Template

```markdown
# [Brand] Voice & Tone Guide

## Our Voice

[Brand] sounds [attribute], [attribute], and [attribute].

### Core Attributes

**1. [Attribute Name]**
- What it means: [Description]
- We are: [Example]
- We're not: [Counter-example]

**2. [Attribute Name]**
[Repeat]

**3. [Attribute Name]**
[Repeat]

## Grammar & Mechanics

- Contractions: [Yes/No]
- Exclamation points: [Use sparingly/Never/Frequently]
- Emojis: [Appropriate contexts]
- Person: [First/Second/Third]
- Active voice: [Always/Usually/Varies]

## Tone by Context

| Context | Tone | Example |
|---------|------|---------|
| Error | Apologetic | "Sorry about that..." |
| Success | Encouraging | "Nice work!" |
| Documentation | Clear | "Follow these steps:" |

## Word Choices

**Preferred:**
- [Word 1] over [Word 2]
- [Word 3] over [Word 4]

**Avoid:**
- [Words/phrases to avoid]

## Examples

### Good Examples
[3-5 examples that nail the voice]

### Before/After
**Before:** [Generic version]
**After:** [Our voice version]
```

---

**Remember:** Your voice should feel authentic, not forced. If it doesn't feel like "you," it won't resonate with your audience.