Skip to main content
The brand-voice.md context file defines your brand’s unique personality, tone, and messaging framework. It ensures all content generated by SEO Machine matches your brand’s voice consistently.

Location

Template: ~/workspace/source/context/brand-voice.md Example: ~/workspace/source/examples/castos/brand-voice.md

What It Defines

The brand voice file contains:
  • Voice Pillars - 3-5 core characteristics that define your brand personality
  • Tone Guidelines - How your voice adapts for different content types
  • Core Messages - Key brand messages to weave throughout content
  • Value Propositions - Specific positioning for each customer segment
  • Writing Style - Sentence structure, word choice, and formatting preferences
  • Audience Understanding - Who you write for and what they care about

Voice Pillars

Voice pillars are the foundation of your brand personality. Each pillar should include:

Structure

### 1. [Pillar Name]
- **What it means**: Core concept of this voice characteristic
- **How it sounds**: How this comes across in writing
- **Example**: A sentence demonstrating this pillar
- **Avoid**: What NOT to do

Real Example: Castos

### 1. Professional Yet Approachable
- **What it means**: We're experts in podcasting, but we're not stuffy
- **How it sounds**: Conversational, warm, knowledgeable without condescension
- **Example**: "Podcast hosting doesn't have to be complicated. Here's what you actually need to know."
- **Avoid**: Overly technical jargon without explanation, corporate-speak, talking down to readers

Choosing Your Voice Pillars

Good voice pillars are:
  1. Specific - “Professional yet approachable” not just “professional”
  2. Actionable - Clear guidance on how to write
  3. Differentiated - Unique to your brand
  4. Consistent - All pillars work together harmoniously
Questions to ask:
  • How do we want customers to perceive us?
  • What makes our brand different from competitors?
  • What personality traits reflect our company culture?
  • How would we describe our brand to a friend?

Tone Guidelines

General Tone

Define your overall tone with a clear metaphor: Castos Example:
Imagine you’re an experienced podcaster helping a friend succeed. You know what you’re talking about, you genuinely want them to succeed, and you explain things clearly without being patronizing.

Tone by Content Type

Your tone should adapt based on content type while maintaining core voice:
**How-To Guides**: Instructive, step-by-step, encouraging
- "First, you'll want to..."
- "Now that you've completed X, let's move on to Y."
- "Don't worry if this seems confusing at first—it'll click once you try it."

**Strategy Content**: Authoritative, experienced, actionable
- "Here's what successful podcasters do differently..."
- "The most effective approach is..."
- "Based on our analysis of 10,000+ podcasts..."

**Industry News**: Insightful, analytical, forward-looking
- "This shift means podcast creators need to..."
- "The podcasting landscape is evolving toward..."
- "Here's why this matters for your show..."

**Product Content**: Benefit-focused, clear, honest
- "This feature solves the problem of..."
- "You can use this to..."
- "Here's how it works in practice..."

Core Brand Messages

Define 3-5 key messages that should be woven throughout content:

Structure

#### Message 1: [Message Title]
- **Concept**: One sentence describing the core message
- **Key Points**:
  - Supporting point 1
  - Supporting point 2
  - Supporting point 3
- **Usage**: When discussing [relevant topics]

Real Example: Castos

#### Message 1: Podcasting Made Simple
- **Concept**: Podcast hosting and growth shouldn't require technical expertise
- **Key Points**:
  - Intuitive tools that just work
  - No steep learning curve
  - Focus on creating, not troubleshooting
- **Usage**: When discussing platform features, ease of use, user experience

How to Use Core Messages

Core messages are themes to incorporate, not scripts to repeat verbatim: Don’t: Force the same message into every article Do: Naturally weave relevant messages into appropriate content Example: In an article about podcast editing software, incorporate “Podcasting Made Simple” by emphasizing intuitive interfaces and easy workflows.

Value Propositions

Define specific positioning for each customer segment:
**For New Podcasters**:
"Start your podcast without the technical headaches. Castos handles the
complexity so you can focus on creating great content."

**For Growing Shows**:
"Scale your podcast with advanced analytics, monetization tools, and
marketing features that drive audience growth."

**For Professional Networks**:
"Manage multiple shows with enterprise-grade hosting, team collaboration,
and white-label options for your brand."

Writing Style Guidelines

Sentence Structure

Define preferences for:
  • Length variation - Mix of short and long sentences
  • Voice preference - Active voice percentage
  • Average length - Target words per sentence
  • Clarity standards - Plain language requirements
Example:
- **Vary length**: Mix short punchy sentences with longer explanatory ones
- **Active voice preferred**: "We built this" not "This was built"
- **Average length**: 15-20 words per sentence
- **Clarity first**: If a sentence confuses you, it'll confuse readers

Word Choice

Document specific word preferences:
**Say This****Not That**
- podcast creators → podcasters (more inclusive)
- podcast hosting → podcast storage (hosting is the industry term)
- listeners → subscribers (listeners is more accurate)
- analytics → stats (analytics is more professional)
- monetize → monetise (US spelling)

Terminology

Define industry-specific term usage:
  • Technical terms and when to define them
  • Acronyms and first-use rules
  • Product names and capitalization
  • Competitive product references

Voice Examples

Excellent Voice Example ✅

Provide a full paragraph that demonstrates your brand voice:
Podcast analytics don't have to feel like decoding ancient hieroglyphics.
You need to know three things: who's listening, what they're engaging
with, and where they're dropping off. Everything else is noise. Focus on
those metrics, and you'll make smarter decisions about your content,
marketing, and growth strategy. We built Castos analytics to surface
exactly these insights—no data science degree required.

**Why this works:**
- Conversational and approachable tone
- Simplifies complex topic
- Action-oriented advice
- Natural product mention
- Empowers the reader

Poor Voice Example ❌

Show what NOT to do:
Our enterprise-grade analytics solution provides comprehensive visibility
into your podcast's performance metrics through an intuitive dashboard
interface that leverages cutting-edge data visualization technologies to
deliver actionable insights for stakeholders across the organization.

**Why this fails:**
- Corporate jargon and buzzwords
- Passive and formal tone
- Features over benefits
- No clear action for reader
- Doesn't address reader needs

Audience Understanding

Primary Audience

Define your main target audience in detail:
**Primary Audience**: Independent Podcast Creators
- Creating original content in specific niches
- 100-10,000 downloads per episode
- Solo creators or small teams (1-3 people)
- Limited technical expertise
- Focused on growth and monetization

What They Care About

Document audience priorities and pain points:
**Top Priorities**:
1. Growing their audience
2. Monetizing their content
3. Improving audio quality
4. Understanding their analytics
5. Saving time on technical tasks

**Pain Points**:
1. Technical complexity of podcast hosting
2. Difficulty understanding analytics
3. Time-consuming distribution process
4. Lack of monetization options
5. Challenge of consistent growth

How to Serve Them

Define principles for serving your audience:
- **Respect their time**: Get to the point quickly
- **Make it actionable**: Give specific, implementable advice
- **Explain the 'why'**: Help them understand strategy, not just tactics
- **Acknowledge challenges**: Show we understand their work
- **Celebrate progress**: Encourage incremental improvement

Configuration Steps

1. Copy the Template

cp ~/workspace/source/context/brand-voice.md ~/workspace/source/context/my-brand-voice.md

2. Review the Example

Study the Castos example to understand proper format:
cat ~/workspace/source/examples/castos/brand-voice.md

3. Define Your Voice Pillars

Brainstorm 3-5 characteristics that define your brand:
  • How do customers describe you?
  • What makes your brand different?
  • What personality traits matter to your audience?
  • How do you want to be perceived?

4. Document Tone Variations

Write example phrases for each content type:
  • How-to guides
  • Strategic advice
  • Industry news
  • Product content

5. Articulate Core Messages

Identify 3-5 key themes to incorporate:
  • What do you want people to know about your brand?
  • What unique value do you provide?
  • What problems do you solve?

6. Define Your Audience

Document who you write for:
  • Demographics and firmographics
  • Goals and priorities
  • Challenges and pain points
  • How they consume content

7. Provide Examples

Write both positive and negative examples:
  • Show excellent brand voice in action
  • Demonstrate what NOT to do
  • Explain why each example works or fails

8. Test and Refine

Generate sample content and evaluate:
/write "Test Article Topic"
Review output and refine your brand voice file based on results.

Quality Checklist

Before finalizing your brand voice file:
  • Voice pillars are specific - Not generic traits like “professional”
  • Examples are concrete - Actual sentences, not vague descriptions
  • Tone variations are clear - Distinct guidance for each content type
  • Messages are actionable - Can be naturally incorporated into content
  • Audience is well-defined - Clear understanding of who you serve
  • Terminology is documented - Preferred terms and usage guidelines
  • Positive and negative examples - Show both what to do and avoid
  • Tested with content - Generated content matches your expectations

Common Mistakes

Too Generic

Bad: “Be professional and helpful” Good: “Professional yet approachable—like an experienced podcaster helping a friend succeed”

No Examples

Bad: “Use a conversational tone” Good: “Use a conversational tone: ‘Here’s what you need to know’ not ‘The following information is pertinent‘“

Feature-Focused

Bad: “Mention our advanced features” Good: “Focus on benefits: ‘Save hours with automated distribution’ not ‘Advanced API integration capabilities‘“

Inconsistent Pillars

Bad: Mixing “Fun and playful” with “Serious and authoritative” Good: All pillars should work together harmoniously

Next Steps

Style Guide

Configure grammar and formatting standards

SEO Guidelines

Define SEO optimization requirements

Write Content

Generate content using your brand voice

Context Files Overview

Learn about all context files

Build docs developers (and LLMs) love