Initial commit

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

@@ -0,0 +1,690 @@
+# 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.