UNPKG

aiwg

Version:

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

722 lines (517 loc) 25.5 kB
# Voice & Tone Guide Template --- **Document ID**: BRD-002 **Template Version**: 1.0.0 **Last Updated**: 2025-11-28 **Owner**: Brand Team / Content Strategy **Status**: Living Document --- ## Purpose This guide defines the **voice** (constant personality) and **tone** (adaptive style) for all brand communications. Use this to ensure consistency across channels while adapting appropriately to context and audience emotion. ## Voice vs. Tone **Voice** = Your brand's personality (stays consistent) - Example: "We are helpful, approachable, and expert." **Tone** = Adaptation to context (changes based on situation) - Example: Celebratory when user succeeds, reassuring when user encounters error --- ## 1. Brand Voice Definition ### 1.1 Voice Dimensional Framework Rate your brand position on each scale (0-100% toward each end): #### Dimension 1: Formal ↔ Casual **Position**: [e.g., 70% Casual] **Rationale**: [Why this balance fits your audience and brand] **Examples**: | Formal | Casual | |--------|--------| | "We recommend reviewing your account settings." | "Hey! Quick check—your account settings might need a look." | | "Please submit your inquiry via the contact form." | "Got a question? Just hit us up through the form!" | | "Our analysis indicates significant improvement." | "Great news—things are looking way better!" | **Your Brand Voice**: - ✓ Do: [Specific language your brand uses] - ✗ Don't: [Language too formal or too casual for your position] #### Dimension 2: Respectful ↔ Irreverent **Position**: [e.g., 80% Respectful] **Rationale**: [Explanation] **Examples**: | Respectful | Irreverent | |------------|------------| | "We appreciate your patience during this process." | "We know waiting sucks—thanks for hanging in there!" | | "Your feedback helps us improve." | "Tell us what's broken. We can take it." | | "Industry-leading innovation" | "The stuff everyone else wishes they thought of first" | **Your Brand Voice**: - ✓ Do: - ✗ Don't: #### Dimension 3: Enthusiastic ↔ Matter-of-Fact **Position**: [e.g., 65% Enthusiastic] **Rationale**: [Explanation] **Examples**: | Enthusiastic | Matter-of-Fact | |--------------|----------------| | "We're thrilled to announce our new feature!" | "We've released a new feature." | | "Amazing! You've completed all steps!" | "All steps completed." | | "Transform your workflow with our incredible tools!" | "Improve your workflow with our tools." | **Your Brand Voice**: - ✓ Do: - ✗ Don't: #### Dimension 4: Serious ↔ Funny **Position**: [e.g., 40% Funny] **Rationale**: [Explanation] **Examples**: | Serious | Funny | |---------|-------| | "Data security is our highest priority." | "We guard your data like a dragon guards gold. But less fire-breathing." | | "Our platform ensures reliable performance." | "We keep things running smoother than your morning coffee routine." | | "404 Error: Page not found" | "404: This page went on vacation and forgot to tell us." | **Your Brand Voice**: - ✓ Do: - ✗ Don't: #### Dimension 5: Expert ↔ Friend **Position**: [e.g., 55% Expert] **Rationale**: [Explanation] **Examples**: | Expert | Friend | |--------|--------| | "Our algorithm leverages machine learning to optimize outcomes." | "We use smart tech to make this work better for you." | | "Best practices dictate a multi-layered approach." | "Here's what works—trust us, we've tried everything else." | | "We recommend the following implementation strategy." | "Try this—it's what we'd do ourselves." | **Your Brand Voice**: - ✓ Do: - ✗ Don't: ### 1.2 Voice Character Summary **[Brand Name] sounds like**: [Write 3-5 descriptive phrases that capture your voice] Examples: - "A knowledgeable friend who's genuinely excited to help" - "The colleague who explains complex things without making you feel dumb" - "Professional but never stuffy—wears nice jeans to the meeting" **We are**: - [Adjective 1]: [Definition and example] - [Adjective 2]: [Definition and example] - [Adjective 3]: [Definition and example] - [Adjective 4]: [Definition and example] **We are NOT**: - [Anti-Adjective 1]: [What to avoid] - [Anti-Adjective 2]: [What to avoid] - [Anti-Adjective 3]: [What to avoid] ### 1.3 Brand Archetype **Primary Archetype**: [Select from list] - [ ] **Hero** (Nike): Inspirational, courageous, achievement-oriented - [ ] **Sage** (Google): Knowledge-seeking, thoughtful, authoritative - [ ] **Jester** (Ben & Jerry's): Playful, fun-loving, irreverent - [ ] **Creator** (Adobe): Innovative, imaginative, expressive - [ ] **Caregiver** (Johnson & Johnson): Compassionate, nurturing, protective - [ ] **Ruler** (Mercedes): Authoritative, responsible, organized - [ ] **Explorer** (Patagonia): Adventurous, independent, pioneering - [ ] **Magician** (Disney): Transformative, visionary, charismatic - [ ] **Innocent** (Dove): Pure, optimistic, honest - [ ] **Lover** (Chanel): Passionate, intimate, appreciative - [ ] **Rebel** (Harley-Davidson): Revolutionary, disruptive, provocative - [ ] **Everyperson** (IKEA): Down-to-earth, relatable, authentic **How This Shapes Our Voice**: [Explain how archetypal traits manifest in your writing] --- ## 2. Tone Adaptation Framework ### 2.1 Tone Mapping by Reader Emotion Your **voice** stays constant, but **tone** adapts to context and reader emotional state. #### Situational Tone Matrix | Reader Situation | Reader Emotion | Tone Adaptation | Voice Example | |------------------|----------------|-----------------|---------------| | **Onboarding** | Excited but anxious | Encouraging, clear, step-by-step | "Let's get you set up! This takes about 2 minutes, and we'll guide you through each step." | | **Error Message** | Frustrated, blocked | Apologetic, solution-focused, calm | "Oops—something went wrong. Here's how to fix it: [steps]. Need help? We're here." | | **Success State** | Accomplished, proud | Celebratory, brief, affirming | "Nice work! Your report is ready to share." | | **Billing Issue** | Concerned, anxious | Reassuring, transparent, actionable | "We noticed a payment hiccup. No worries—your account stays active while we sort this out together." | | **Feature Announcement** | Curious, skeptical | Benefit-focused, concrete, enthusiastic | "You asked for faster exports—now they're 3x quicker. Check it out." | | **Technical Documentation** | Task-focused, impatient | Direct, precise, structured | "To configure the API: 1. Generate key. 2. Add to header. 3. Test endpoint." | | **Marketing Email** | Curious, busy | Engaging, value-first, scannable | "Teams like yours save 10 hours/week with [Feature]. Here's how it works." | | **Customer Support** | Frustrated, needs help | Empathetic, patient, solution-driven | "I understand how frustrating this is. Let's fix it together—here's what we'll do." | | **Apology/Crisis** | Upset, betrayed | Sincere, accountable, transparent | "We messed up. Here's exactly what happened, what we're doing, and how we'll prevent this." | | **Upsell/Sales** | Interested but cautious | Consultative, benefit-clear, no pressure | "If [pain point] sounds familiar, [Product] might help. Here's how teams use it." | ### 2.2 Tone Modifiers Use these modifiers to adjust tone within voice parameters: **More Formal** (Serious situations: legal, security, crisis): - Use complete sentences (avoid fragments) - Minimize contractions ("do not" vs. "don't") - Include professional sign-offs - Avoid humor or playfulness - Add context and explanations **More Casual** (Friendly situations: onboarding, success, community): - Use contractions freely ("you're," "we'll") - Conversational sentence structure - Short paragraphs (1-2 sentences) - Okay to use personality and humor - Direct address ("you," "your") **More Empathetic** (User is frustrated, confused, or experiencing hardship): - Acknowledge emotion ("I know this is frustrating") - Use "we" and "together" (partnership language) - Avoid dismissive phrases ("just," "simply," "easy") - Provide clear next steps - Offer human contact option **More Celebratory** (User achieved something, milestone reached): - Use positive affirmations ("Great job!" "Well done!") - Exclamation points (but sparingly—1 per message) - Highlight user effort/achievement - Brief and punchy - Optional emoji (if brand-appropriate) **More Urgent** (Time-sensitive, requires action): - Lead with what user needs to do - Use specific deadlines ("by Friday" not "soon") - Explain consequences clearly - Make CTA obvious - Avoid alarm language (no ALL CAPS, excessive !!!) --- ## 3. Channel-Specific Voice Adaptations ### 3.1 Social Media #### Platform-Specific Tone **LinkedIn** (Professional, Thought Leadership): - Voice Position: [Most Formal / Expert] - Tone: Insightful, industry-focused, authoritative - Post Length: 150-300 words for text posts - Hashtags: 3-5 industry-relevant - Example: "Data security isn't just a feature—it's foundational. Here's how we approach zero-trust architecture at [Brand]." **Twitter/X** (Conversational, Timely): - Voice Position: [Balanced] - Tone: Concise, opinionated, approachable - Post Length: 200-280 characters (readable) - Hashtags: 1-2 max - Example: "Hot take: Your dashboard shouldn't need a manual. If users can't figure it out in 30 seconds, it's our fault, not theirs." **Instagram** (Visual-First, Lifestyle): - Voice Position: [Casual / Friendly] - Tone: Aspirational, human, behind-the-scenes - Caption Length: 125-150 characters (above fold), longer storytelling below - Hashtags: 5-10 (mix popular and niche) - Example: "Monday morning view from our design team's workspace. ☕️ Where does your best work happen?" **TikTok** (Playful, Trend-Aware): - Voice Position: [Most Casual / Funny] - Tone: Unpolished, authentic, trend-responsive - Video Length: 30-60 seconds (sweet spot) - Text Overlay: Short, punchy, easy to read - Example: [On-screen text] "POV: You just automated a 4-hour task" [Celebratory reaction] **YouTube** (Educational, In-Depth): - Voice Position: [Expert / Helpful] - Tone: Personable, sustained engagement, educational - Video Length: 8-15 minutes (tutorial), 3-5 (announcement) - Title: Clear value proposition + curiosity gap - Example Title: "How We Cut API Response Time by 60% (Without Rewriting Code)" #### Social Media Response Templates **Positive Feedback**: - Thank: "Thanks [Name]! So glad this helped." - Amplify: "This is exactly what we built it for!" - Invite: "Would love to hear how you're using it—DM us?" **Negative Feedback**: - Acknowledge: "We hear you, [Name]. This isn't the experience we want for you." - Empathize: "Totally understand your frustration." - Move to Private: "Can you DM us details? We'd like to make this right." **Questions**: - Answer Directly: Lead with the answer, then context - Link Resources: "Here's a guide that walks through this: [link]" - Humanize: "Great question! Here's how it works..." **Trolls/Spam**: - Ignore: Don't engage with obvious trolls - Boundary-Setting (if needed): "We're here for productive conversations. Let's keep it respectful." ### 3.2 Email #### Email Type Tone Guide **Transactional Emails** (Receipts, Confirmations): - Tone: Clear, functional, minimal personality - Subject: Descriptive, action-oriented ("Your Receipt from [Brand]") - Body: Essential info only, obvious CTA - Example: "Thanks for your purchase! Your receipt is attached. Questions? Reply to this email." **Onboarding Emails** (Welcome Series): - Tone: Encouraging, instructional, supportive - Subject: Benefit-focused ("Get the most out of [Product]") - Body: 1-2 key actions per email, short paragraphs - Example: "Welcome to [Brand]! Let's get you started with the #1 feature our users love: [Feature]. Click here to try it now." **Promotional Emails** (Sales, Offers): - Tone: Persuasive, benefit-focused, time-sensitive - Subject: Value + urgency ("Save 20% this week only") - Body: Lead with benefit, clear CTA, easy to scan - Example: "You've been thinking about [Product]. This week, it's 20% off—and here's why teams are switching..." **Newsletters** (Content, Updates): - Tone: Informative, conversational, value-driven - Subject: Curiosity + value ("3 shortcuts you didn't know existed") - Body: Scannable sections, mix of content types - Example: "Hey [Name], this month we're sharing 3 workflow hacks our power users swear by. Here's the first..." **Customer Support** (Help, Troubleshooting): - Tone: Empathetic, solution-oriented, patient - Subject: Reference ticket/issue ("Re: Your question about [Topic]") - Body: Acknowledge issue, provide solution, offer next steps - Example: "Hi [Name], sorry you're running into this! Here's how to fix it: [steps]. Let me know if this doesn't solve it—I'm here to help." #### Email Subject Line Formula **Length**: 40-60 characters (mobile optimization) **Structure**: [Value/Benefit] + [Specificity/Curiosity] **Examples**: - "Your export is ready" (Transactional) - "3 features that save you 5 hours/week" (Newsletter) - "Last chance: 25% off ends tonight" (Promotional) - "We fixed the bug you reported" (Support) **Avoid**: - ALL CAPS - Excessive punctuation (!!!, ???) - Spam triggers ("Free," "Act now," "Limited time") - Clickbait without delivering value ### 3.3 Website Copy #### Homepage Tone: Confident, Benefit-Clear, Inviting - Hero Headline: Problem + Solution in 10 words - Subheadline: Expand on benefit (1 sentence) - CTA: Action-oriented, specific ("Start Free Trial" not "Learn More") **Example**: - Headline: "Turn customer feedback into product decisions—in minutes, not weeks." - Subheadline: "Analyze thousands of support tickets, reviews, and surveys automatically. See what matters most." - CTA: "See how it works" #### Product Pages Tone: Detailed, Proof-Driven, Consultative - Lead with problem user experiences - Feature → Benefit translation ("AI categorization" → "Never manually tag a ticket again") - Include proof points (metrics, testimonials, case studies) #### Error Pages (404, 500) Tone: Helpful, Light, Human - Acknowledge the error (briefly) - Provide next steps (search, home, contact) - Okay to add light humor (if brand-appropriate) **Example**: - **404**: "Hmm, this page seems to have wandered off. Let's get you back on track: [Search] [Home] [Contact]" - **500**: "Something broke on our end (not yours). We're fixing it. Try again in a few minutes?" ### 3.4 In-Product/UX Writing #### Microcopy Principles **Buttons**: Action verb + object ("Save Changes," "Delete Account," "Download Report") **Empty States**: Explain what goes here + how to add it - Example: "No reports yet. Create your first one to see data visualizations here." **Tooltips**: 1 sentence max, answers "What is this?" or "Why does this matter?" **Success Messages**: Brief, affirming, next-step optional - Example: "Saved! Your changes are live." **Error Messages**: What happened + how to fix + help option - Example: "File too large (max 10MB). Try compressing it or contact support." **Loading States**: Set expectations for wait time - Example: "Analyzing 1,247 tickets... This usually takes 30 seconds." **Confirmation Dialogs**: Clarify consequence + give clear options - Example: "Delete this report? This can't be undone. [Cancel] [Delete Report]" --- ## 4. Writing Style Standards ### 4.1 Grammar & Mechanics **Contractions**: [Use freely / Use in casual contexts / Avoid] - Your Brand: [Choice and rationale] **Oxford Comma**: [Yes / No] - Your Brand: [Choice] - Example: "We offer analytics, reports, and dashboards." (Oxford comma used) **Numbers**: - Spell out: one through nine - Numerals: 10 and above - Exception: Always numerals for metrics, percentages, dates **Capitalization**: - Sentence case for headlines (not Title Case) - Product names: [Your rules] - Feature names: [Your rules] **Active Voice Preferred**: - ✓ "We released a new feature" (active) - ✗ "A new feature was released" (passive) - Exception: When subject is unknown or de-emphasizing actor ### 4.2 Inclusive Language **Pronouns**: - Use "they/them" as singular when gender unknown - Avoid "he or she"—rewrite to plural or use "they" **Gendered Terms to Avoid**: - "guys" → "folks," "everyone," "team," "y'all" - "man-hours" → "person-hours" or "work hours" - "salesman" → "salesperson" or "sales representative" **Ableist Metaphors to Avoid**: - "blind spot" → "oversight," "gap" - "tone deaf" → "insensitive," "out of touch" - "crippled by" → "hindered by," "limited by" - "falling on deaf ears" → "being ignored" **Person-First Language**: - ✓ "person with a disability" - ✗ "disabled person" (unless community preference) **Socioeconomic Sensitivity**: - ✓ "people experiencing homelessness" - ✗ "the homeless" ### 4.3 AI Content Guidelines #### When AI Is Acceptable **Approved Use Cases**: - First drafts for internal documentation - Brainstorming headline variations - SEO meta description generation - Translation starting points - Data summaries **Requires 100% Human Review**: - All customer-facing content - Legal, security, or compliance messaging - Crisis communications or apologies - Executive voice (CEO announcements, thought leadership) - Highly creative or branded campaigns #### AI Pattern Avoidance **Red Flags to Edit Out**: - Hedging: "It's important to note," "It's worth mentioning" - Over-transitions: "Moreover," "Furthermore," "In conclusion" - Formulaic structure: Claim → evidence → restatement (every paragraph) - Lists without connective narrative - Lack of specificity (vague claims without examples) - No clear perspective or opinions **Authenticity Markers to Add**: - Specific examples from real experience - Clear opinions ("We believe," "In our experience") - Acknowledgment of trade-offs ("This approach works best when X, but if Y, consider Z") - Conversational asides (parentheticals, em-dashes) - Varied sentence structure (mix short and long) - Domain-appropriate jargon used naturally #### AI Voice Training Prompt Template ``` Write in [Brand Name]'s voice with these parameters: - Casual: 70% - Helpful: 90% - Expert: 60% - Funny: 30% Context: [User just signed up and needs onboarding guidance] Reader emotion: [Excited but slightly anxious] Tone: [Encouraging, clear, step-by-step] Task: [Write welcome email introducing first feature] Constraints: - Keep under 150 words - 1 clear CTA - Avoid phrases: "It's important to note," "Moreover," "Lastly" - Include specific benefit (not generic "improve productivity") ``` --- ## 5. Voice & Tone Examples ### 5.1 Before & After Examples #### Example 1: Error Message **Before** (Generic, cold): "Error 502: Bad Gateway. The server encountered a temporary error and could not complete your request." **After** (Brand voice): "Whoops—something hiccuped on our end (error 502). Try refreshing in a minute. Still stuck? Contact support—we're on it." #### Example 2: Feature Announcement **Before** (Corporate, vague): "We are pleased to announce the release of our new reporting functionality, which enables users to generate comprehensive analytics dashboards with enhanced customization capabilities." **After** (Brand voice): "New: Build custom dashboards in 3 clicks. Drag, drop, done. Check it out in Reports > Dashboards." #### Example 3: Onboarding Email **Before** (Formal, overwhelming): "Welcome to [Product]. To maximize the value of your subscription, we recommend completing the following setup procedures: 1) Configure your account settings, 2) Integrate your data sources, 3) Invite team members, 4) Review our documentation library." **After** (Brand voice): "Welcome! Let's get you set up. Start here: connect your data (takes 2 min). We'll handle the rest. Questions? Hit reply—a real human will answer." ### 5.2 Cross-Channel Voice Consistency **Same Message, Different Channels**: **Situation**: Announcing new integration with Slack **Website** (Detailed, SEO-optimized): "Integrate [Product] with Slack to receive real-time alerts, share reports with your team, and trigger workflows—all without leaving your workspace. Set up in under 5 minutes." **Email** (Benefit-focused, personal): "Hey [Name], great news: [Product] now works inside Slack. Get alerts, share reports, and trigger actions—right in your channels. Connect in 2 clicks." **Twitter** (Concise, timely): "We're now on Slack. Get your reports and alerts where you already are. Set up in 2 minutes: [link]" **LinkedIn** (Professional, industry context): "60% of teams use Slack as their central hub. Now [Product] lives there too—alerts, reporting, and workflow automation integrated seamlessly. Learn how teams are using it: [link]" **In-App Notification** (Actionable, brief): "New: Slack integration available. Connect now in Settings > Integrations." --- ## 6. Quality Assurance ### 6.1 Voice Checklist Before publishing, verify: - [ ] **Sounds like our brand**: Could a customer recognize this as our voice without seeing the logo? - [ ] **Appropriate tone for context**: Does the tone match reader emotion and situation? - [ ] **Clear and concise**: No unnecessary words or jargon obscuring the message? - [ ] **Active voice**: Passive voice only when intentional? - [ ] **Inclusive language**: No gendered, ableist, or exclusionary terms? - [ ] **Specific examples**: Concrete details instead of vague claims? - [ ] **Authentic perspective**: Clear opinions or point of view? - [ ] **No AI patterns**: Hedging, over-transitions, formulaic structure removed? ### 6.2 Tone Testing **Ask**: 1. If I were the reader in this situation, how would I feel? 2. Does our tone acknowledge that emotion? 3. Does the tone help the reader accomplish their goal? 4. Is the tone appropriate for the relationship stage (new user vs. longtime customer)? ### 6.3 Automated Checking Tools **Voice Compliance**: - **Grammarly Business**: Set brand voice preset, check tone - **Acrolinx**: Enterprise brand voice + inclusivity checking - **Hemingway Editor**: Readability (target Grade 8-10 for general audience) **Inclusive Language**: - **Alex.js**: CLI tool for insensitive language detection - **Conscious Language Badge**: Browser extension --- ## 7. Training & Resources ### 7.1 Onboarding for New Team Members **Week 1**: - Read this Voice & Tone Guide - Review 10 examples of brand content (best-in-class) - Complete voice quiz (identify brand vs. off-brand samples) **Week 2**: - Write 3 samples in brand voice (error message, email, social post) - Review with content lead - Revise based on feedback **Ongoing**: - Attend monthly content review sessions - Contribute to voice guide updates (quarterly) ### 7.2 Voice & Tone Workshop **90-Minute Session**: 1. **Voice Foundation** (15 min): Review dimensional framework 2. **Tone Mapping Exercise** (20 min): Practice adapting tone to scenarios 3. **Channel Practice** (30 min): Rewrite same message for 3 channels 4. **Group Critique** (20 min): Review real examples, identify voice consistency 5. **Q&A** (5 min) **Materials**: - [Link to workshop deck] - [Link to practice exercises] ### 7.3 Reference Library **Best Examples** (Internal Archive): - [Folder/link to approved content samples organized by type] **Anti-Examples** (What Not to Do): - [Folder/link to off-brand samples with explanations] **Voice Evolution Log**: - [Document tracking how voice has evolved, with rationale for changes] --- ## 8. Governance & Updates ### 8.1 Voice Drift Monitoring **Quarterly Audits**: - Sample 50 pieces of published content - Score against voice dimensions (1-5 scale) - Identify patterns of drift - Update training if needed **Tools**: - Acrolinx Brand Voice Score (automated) - Manual review with scorecard ### 8.2 Feedback Loop **How to Suggest Changes**: - Submit via [form/email/Slack channel] - Include: Current guideline, proposed change, rationale, examples - Review by content lead (monthly) - Approved changes incorporated in quarterly updates ### 8.3 Version History **Current Version**: 1.0.0 **Changelog**: **[1.0.0] - 2025-01-15** - Initial voice & tone guide - Dimensional framework established - Channel-specific guidelines added - AI content governance included --- ## 9. Quick Reference ### Do's - ✓ Use contractions in casual contexts - ✓ Lead with benefits, not features - ✓ Write like you talk (read aloud test) - ✓ Address reader as "you" - ✓ Be specific (numbers, examples, names) - ✓ Front-load key information - ✓ Use active voice - ✓ Keep sentences under 25 words - ✓ Break long paragraphs (2-3 sentences max) ### Don'ts - ✗ Use jargon without explanation - ✗ Hedge ("kind of," "sort of," "perhaps") - ✗ Over-transition ("Moreover," "Furthermore") - ✗ Write long-winded sentences - ✗ Use passive voice unnecessarily - ✗ Rely on exclamation points for energy - ✗ Sound like a robot (overly formal) - ✗ Make unsubstantiated claims - ✗ Use gendered or ableist language --- ## Contact **Content Team**: content@[company].com **Slack Channel**: #content-voice **Office Hours**: [Schedule] **Feedback**: [How to submit suggestions for guide improvements] --- **Document Ownership**: Content Strategy Team **Review Cycle**: Quarterly **Next Review Date**: [Date] **Living Document URL**: [Link] --- *This voice & tone guide is a living document. For questions, exceptions, or feedback, contact the Content Team.*