OpenWriterControle/.opencode/context/content/tone-voice.md

# Tone & Voice Guidelines

**Category**: content  
**Purpose**: Maintaining consistent brand voice and adapting tone for different contexts  
**Used by**: copywriter, technical-writer

---

## Overview

Voice is your brand's personality - it stays consistent. Tone is how that voice adapts to different situations and audiences. This guide helps maintain consistency while being contextually appropriate.

## Voice vs. Tone

### Voice (Consistent)
Your brand's personality that never changes:
- Professional but approachable
- Knowledgeable but not condescending
- Confident but humble
- Clear and direct

### Tone (Adaptive)
How voice adapts to context:
- **Error messages**: Apologetic, helpful
- **Success messages**: Encouraging, celebratory
- **Marketing**: Enthusiastic, persuasive
- **Documentation**: Clear, instructional
- **Support**: Empathetic, solution-focused

## Voice Dimensions

### 1. Formality Spectrum

**Formal** ←→ **Casual**

**Formal**:
```
"We appreciate your business and look forward to serving you."
```

**Casual**:
```
"Thanks for choosing us! We're excited to work with you."
```

**Choose based on**:
- Industry norms
- Audience expectations
- Context (legal vs. social)

### 2. Enthusiasm Spectrum

**Reserved** ←→ **Enthusiastic**

**Reserved**:
```
"Your account has been created successfully."
```

**Enthusiastic**:
```
"Welcome aboard! Your account is ready to go! 🎉"
```

**Choose based on**:
- Moment significance
- User emotional state
- Brand personality

### 3. Expertise Spectrum

**Educational** ←→ **Expert**

**Educational**:
```
"Let's walk through this step by step. First, click the 
'Settings' button in the top right corner."
```

**Expert**:
```
"Navigate to Settings > Advanced > API Configuration."
```

**Choose based on**:
- User expertise level
- Content complexity
- Context (onboarding vs. advanced docs)

## Tone Guidelines by Context

### 1. Marketing Copy

**Characteristics**:
- Enthusiastic and persuasive
- Benefit-focused
- Action-oriented
- Emotionally engaging

**Example**:
```
"Transform your workflow in minutes, not months. Join 10,000+ 
teams who've already made the switch."
```

### 2. Product Documentation

**Characteristics**:
- Clear and instructional
- Step-by-step
- Neutral tone
- Technically accurate

**Example**:
```
"To configure authentication:
1. Navigate to Settings > Security
2. Click 'Add Authentication Method'
3. Select your preferred provider"
```

### 3. Error Messages

**Characteristics**:
- Apologetic but not overly so
- Explain what happened
- Provide clear next steps
- Never blame the user

**Bad**:
```
"Error: Invalid input. Try again."
```

**Good**:
```
"We couldn't process your request because the email format 
isn't valid. Please check and try again."
```

### 4. Success Messages

**Characteristics**:
- Positive and encouraging
- Confirm what happened
- Suggest next steps
- Celebrate wins

**Example**:
```
"Great! Your changes have been saved. Ready to publish?"
```

### 5. Support Communication

**Characteristics**:
- Empathetic and understanding
- Solution-focused
- Patient and helpful
- Personalized

**Example**:
```
"I understand how frustrating this must be. Let's get this 
sorted out for you. Can you tell me what you see when you 
click the 'Export' button?"
```

### 6. Onboarding

**Characteristics**:
- Welcoming and encouraging
- Educational without overwhelming
- Progressive disclosure
- Celebrate small wins

**Example**:
```
"Welcome! Let's get you set up in 3 quick steps. 
First, let's create your workspace."
```

## Writing Principles

### 1. Be Clear and Concise

**Before**:
```
"In order to facilitate the process of account creation, 
it is necessary for you to provide your email address."
```

**After**:
```
"Enter your email to create your account."
```

### 2. Use Active Voice

**Passive**:
```
"Your password has been reset by our system."
```

**Active**:
```
"We've reset your password."
```

### 3. Write for Humans

**Robotic**:
```
"Operation completed successfully. Proceed to next step."
```

**Human**:
```
"All set! What would you like to do next?"
```

### 4. Be Inclusive

**Exclusive**:
```
"Hey guys, check out our new feature!"
```

**Inclusive**:
```
"Check out our new feature!"
```

### 5. Avoid Jargon

**Jargon-heavy**:
```
"Leverage our API to synergize your tech stack."
```

**Clear**:
```
"Connect our API to your existing tools."
```

## Emotional Tone Mapping

### User Emotional State → Appropriate Tone

**User is frustrated** → Empathetic, solution-focused
```
"I know this is frustrating. Let's fix this together."
```

**User achieved something** → Celebratory, encouraging
```
"Awesome work! You've completed your first project."
```

**User is confused** → Patient, educational
```
"No worries! Let me break this down for you."
```

**User made an error** → Helpful, non-judgmental
```
"Looks like there's a small issue. Here's how to fix it."
```

**User is new** → Welcoming, supportive
```
"Welcome! We're here to help you get started."
```

## Brand Voice Examples

### Example 1: Tech Startup (Friendly, Modern)
```
Voice: Approachable, innovative, helpful
Tone variations:
- Marketing: "Build amazing things, faster"
- Error: "Oops! Something went wrong. Let's try that again."
- Success: "Nice! You're all set."
```

### Example 2: Enterprise SaaS (Professional, Trustworthy)
```
Voice: Professional, reliable, expert
Tone variations:
- Marketing: "Enterprise-grade security you can trust"
- Error: "We encountered an issue. Please contact support."
- Success: "Configuration saved successfully."
```

### Example 3: Creative Tool (Inspiring, Playful)
```
Voice: Creative, inspiring, fun
Tone variations:
- Marketing: "Unleash your creativity"
- Error: "Hmm, that didn't work. Let's try something else!"
- Success: "Beautiful! Your design is ready to share."
```

## Best Practices

1. **Create a voice chart** - Document your brand's voice attributes
2. **Use real examples** - Show, don't just tell
3. **Consider context** - Adapt tone to situation
4. **Be consistent** - Use the same voice across channels
5. **Avoid clichés** - "Think outside the box," "game-changer"
6. **Use contractions** - "We're" not "We are" (unless formal)
7. **Address the user** - Use "you" and "your"
8. **Be specific** - Concrete details over vague statements
9. **Test with users** - Does it resonate?
10. **Update regularly** - Voice evolves with your brand

## Anti-Patterns

- ❌ **Inconsistent voice** - Confuses users about your brand
- ❌ **Overly formal** - Creates distance from users
- ❌ **Too casual** - May seem unprofessional
- ❌ **Jargon overload** - Excludes non-experts
- ❌ **Passive voice** - Weakens your message
- ❌ **Blaming users** - "You entered the wrong password"
- ❌ **Fake enthusiasm** - "Amazing! Incredible! Awesome!" overuse
- ❌ **Corporate speak** - "Leverage synergies to optimize"

## Voice & Tone Checklist

Before publishing, verify:
- [ ] Does this sound like our brand?
- [ ] Is the tone appropriate for the context?
- [ ] Is it clear and easy to understand?
- [ ] Does it use active voice?
- [ ] Is it free of jargon?
- [ ] Does it address the user directly?
- [ ] Is it inclusive and respectful?
- [ ] Does it match our voice chart?
- [ ] Would I say this to someone in person?
- [ ] Does it help the user accomplish their goal?

## References

- Nicely Said by Nicole Fenton & Kate Kiefer Lee
- The Voice and Tone Guide by MailChimp
- Conversational Design by Erika Hall