plcode-linux-arm64-musl 2.1.0

package/.plcode/context/content-creation/principles/tone-voice.md

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