8.6 KiB

Raw Blame History

Brand Voice & Tone Guidelines

Reference for maintaining consistent voice across all written content. These are defaults — override with client-specific guidelines when available.

Voice Archetypes

Choose one primary archetype per brand. A secondary archetype can add nuance but should never dominate.

Expert

Sounds like: A senior practitioner sharing hard-won knowledge.
Characteristics: Precise, evidence-backed, confident without arrogance. Cites data, references real-world experience, and isn't afraid to say "it depends."
Typical vocabulary: "In practice," "the tradeoff is," "based on our benchmarks," "here's why this matters."
Risk to avoid: Coming across as condescending or overly academic.
Best for: Technical audiences, B2B SaaS, engineering blogs, whitepapers.

Guide

Sounds like: A patient teacher walking you through something step by step.
Characteristics: Clear, encouraging, anticipates confusion. Breaks complex ideas into digestible pieces. Uses analogies.
Typical vocabulary: "Let's start with," "think of it like," "the key thing to remember," "don't worry if this seems complex."
Risk to avoid: Being patronizing or oversimplifying for an advanced audience.
Best for: Tutorials, onboarding content, documentation, beginner-to-intermediate audiences.

Innovator

Sounds like: Someone who sees around corners and wants to bring you along.
Characteristics: Forward-looking, curious, willing to challenge assumptions. Connects dots across domains. Thinks in systems.
Typical vocabulary: "What if," "the shift we're seeing," "this changes the calculus," "the next wave."
Risk to avoid: Sounding like hype or vaporware. Must ground vision in evidence.
Best for: Thought leadership, industry analysis, product vision content, founder blogs.

Friend

Sounds like: A sharp colleague sharing advice over coffee.
Characteristics: Warm, direct, conversational. Uses "you" and "we." Comfortable with humor when it's natural. Doesn't hide behind jargon.
Typical vocabulary: "Here's the thing," "honestly," "we've all been there," "the trick is."
Risk to avoid: Being too casual for high-stakes topics or enterprise audiences.
Best for: Community content, newsletters, brand blogs aimed at practitioners.

Motivator

Sounds like: A coach who believes in your potential and pushes you to act.
Characteristics: Energetic, action-oriented, focused on outcomes. Uses imperatives. Celebrates progress.
Typical vocabulary: "Start today," "you can do this," "here's your edge," "stop waiting for perfect."
Risk to avoid: Empty cheerleading. Must pair motivation with substance.
Best for: Career content, productivity content, entrepreneurship, course marketing.

Core Writing Principles

These apply regardless of archetype.

1. Clarity First

If a sentence can be misread, rewrite it.
Use the simplest word that conveys the precise meaning. "Use" over "utilize." "Start" over "commence."
One idea per paragraph. One purpose per section.
Define jargon on first use, or skip it entirely.

2. Customer-Centric

Frame everything from the reader's perspective, not the company's.
Instead of: "We built a new feature that enables real-time collaboration."
Write: "You can now edit documents with your team in real time."
Lead with the reader's problem or goal, not the product or solution.

3. Active Voice

Active voice is the default. Passive voice is acceptable only when the actor is unknown or irrelevant.
Active: "The script generates a report every morning."
Passive (acceptable): "The logs are rotated every 24 hours." (The actor doesn't matter.)
Passive (avoid): "A decision was made to deprecate the endpoint." (Who decided?)

4. Show, Don't Claim

Replace vague claims with specific evidence.
Claim: "Our platform is incredibly fast."
Show: "Queries return in under 50ms at the 99th percentile."
If you can't provide evidence, soften the language or cut the sentence.

Tone Attributes

Tone shifts based on content type and audience. Use these spectrums to calibrate.

Formality Spectrum

Casual -------|-------|-------|-------|------- Formal
  1       2       3       4       5

Level	Description	Use When
1	Slang OK, sentence fragments, first person	Internal team comms, very informal blogs
2	Conversational, contractions, direct address	Newsletters, community posts, most blog content
3	Professional but approachable, minimal contractions	Product announcements, mid-funnel content
4	Polished, structured, no contractions	Whitepapers, enterprise case studies, executive briefs
5	Formal, third person, precise terminology	Legal, compliance, academic partnerships

Default for most blog/article content: Level 2-3.

Technical Depth Spectrum

General -------|-------|-------|-------|------- Deep Technical
    1       2       3       4       5

Level	Description	Use When
1	No jargon, analogy-heavy, conceptual	Non-technical stakeholders, general audience
2	Light jargon (defined inline), practical focus	Business audience with some domain familiarity
3	Industry-standard terminology, code snippets OK	Practitioners who do the work daily
4	Assumes working knowledge, implementation details	Developers, engineers, technical decision-makers
5	Deep internals, performance analysis, tradeoff math	Senior engineers, architects, researchers

Default: Match the audience. When unsure, aim one level below what you think the audience can handle. Accessibility wins.

Language Preferences

Use Action Verbs

Lead sentences — especially headings and CTAs — with strong verbs.

Weak	Strong
There is a way to improve	Improve
This section is a discussion of	This section covers
You should consider using	Use
It is important to note that	Note:
We are going to walk through	Let's walk through

Be Concrete and Specific

Vague language erodes trust. Replace generalities with specifics.

Vague	Concrete
"significantly faster"	"3x faster" or "reduced from 12s to 2s"
"a large number of users"	"over 40,000 monthly active users"
"best-in-class"	describe the specific advantage
"seamless integration"	"connects via a single API call"
"in the near future"	"by Q2" or "in the next release"

Avoid These Patterns

Weasel words: "very," "really," "extremely," "quite," "somewhat" — cut them or replace with data.
Nominalizations: "implementation" when you mean "implement," "utilization" when you mean "use."
Hedge stacking: "It might potentially be possible to perhaps consider..." — commit to a position or state the uncertainty once, clearly.
Buzzword chains: "AI-powered next-gen synergistic platform" — describe what it actually does.

Pre-Publication Checklist

Run through this before publishing any piece of content.

Voice Consistency

Does the piece sound like one person wrote it, beginning to end?
Does it match the target voice archetype?
Are there jarring shifts in tone between sections?
If multiple authors contributed, has it been edited for a unified voice?

Clarity

Can a reader in the target audience understand every sentence on the first read?
Is jargon defined or avoided?
Are all acronyms expanded on first use?
Do headings accurately describe the content beneath them?
Is the article scannable? (subheadings every 2-4 paragraphs, short paragraphs, lists where appropriate)

Value

Does the introduction make clear what the reader will gain?
Does every section earn its place? (Cut anything that doesn't serve the reader's goal.)
Are claims supported by evidence, examples, or data?
Is the advice actionable — can the reader do something with it today?
Does the conclusion provide a clear next step?

Formatting

Title is under 70 characters and includes the core keyword or topic.
Meta description is 140-160 characters and summarizes the value proposition.
Headings use parallel structure (all questions, all noun phrases, or all verb phrases — not mixed).
Code blocks, tables, and images have context (a sentence before them explaining what the reader is looking at).
Links use descriptive anchor text, not "click here."
No walls of text — maximum 4 sentences per paragraph for web content.

8.6 KiB Raw Blame History