6.9 KiB
6.9 KiB
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
Start with Expert but also work in Guide when appliciable.
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.
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 at what you think the audience can handle. We are mostly B2B.
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?
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 includes the core keyword or topic and at least 2 closely related keyword's/topics.
- Meta description summarizes the value proposition.
- 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 5 sentences per paragraph for web content. Use a minimum of 2 sentences.