Back to Zed

Brand Voice Rubric

docs/.conventions/brand-voice/rubric.md

0.228.06.4 KB
Original Source

Brand Voice Rubric

Score each criterion 1-5. Copy must score 4+ on ALL criteria to pass.


1. Technical Grounding (1-5)

Does the copy make specific, verifiable technical claims?

ScoreDescription
5Precise technical details that can be verified (specs, architecture, measurable outcomes)
4Concrete technical claims with clear meaning
3Mix of specific and vague technical references
2Mostly abstract with occasional technical terms
1No technical substance; pure marketing language

Examples:

  • ✅ "Written in Rust with GPU-accelerated rendering at 120fps"
  • ❌ "Blazingly fast performance that will transform your workflow"

2. Natural Syntax (1-5)

Does the writing flow like natural speech from a thoughtful developer?

ScoreDescription
5Varied sentence structure, natural rhythm, reads aloud smoothly
4Mostly natural with minor rhythm issues
3Some AI patterns visible but not dominant
2Obvious structural patterns (parallel triplets, em dash chains)
1Robotic cadence, formulaic construction throughout

Red flags: Em dash overuse, "It's not X, it's Y" constructions, triple parallel lists, sentences all same length.


3. Quiet Confidence (1-5)

Does the copy state facts without hype or emotional manipulation?

ScoreDescription
5Facts speak for themselves; reader draws own conclusions
4Confident statements with minimal flourish
3Some restraint but occasional hype creeps in
2Frequent superlatives or emotional appeals
1Aggressive marketing tone, telling reader how to feel

Examples:

  • ✅ "Zed renders every frame on the GPU. You'll notice the difference when you scroll."
  • ❌ "Experience the revolutionary speed that will absolutely transform how you code!"

4. Developer Respect (1-5)

Does the copy treat the reader as a peer, not a prospect?

ScoreDescription
5Peer-to-peer conversation; assumes technical competence
4Respectful with appropriate technical depth
3Slightly patronizing or oversimplified
2Condescending explanations or forced enthusiasm
1Treats reader as uninformed consumer to be persuaded

Examples:

  • ✅ "Tree-sitter provides incremental parsing, so syntax highlighting updates as you type."
  • ❌ "Don't worry about the technical details — just know it's fast!"

5. Information Priority (1-5)

Is the most important information first?

ScoreDescription
5Key fact or change leads; context follows naturally
4Important info near top with minor preamble
3Buried lede but recoverable
2Significant buildup before substance
1Key information buried or missing entirely

Examples:

  • ✅ "Inline completions now stream token-by-token. Previously, you waited for the full response."
  • ❌ "We've been thinking a lot about the developer experience, and after months of work, we're thrilled to share that..."

6. Specificity (1-5)

Are claims concrete and measurable?

ScoreDescription
5Every claim is specific and verifiable
4Mostly specific with rare abstractions
3Mix of concrete and vague claims
2Mostly abstract benefits
1All claims are vague or unverifiable

Examples:

  • ✅ "Startup time under 100ms on M1 Macs"
  • ❌ "Lightning-fast startup that respects your time"

7. Voice Consistency (1-5)

Does the tone remain unified throughout?

ScoreDescription
5Single coherent voice from start to finish
4Minor tonal shifts that don't distract
3Noticeable drift between sections
2Multiple competing voices
1Jarring tonal inconsistency

Check for: Shifts between casual/formal, technical/marketing, confident/hedging.


8. Earned Claims (1-5)

Are assertions supported or supportable?

ScoreDescription
5Every claim can be demonstrated or verified
4Claims are reasonable and mostly verifiable
3Some unsupported assertions
2Multiple unverifiable superlatives
1Bold claims with no backing

Examples:

  • ✅ "Built by the team behind Atom and Tree-sitter"
  • ❌ "The most advanced editor ever created"

Quick Scoring Template

| Criterion           | Score | Notes |
|---------------------|-------|-------|
| Technical Grounding |   /5  |       |
| Natural Syntax      |   /5  |       |
| Quiet Confidence    |   /5  |       |
| Developer Respect   |   /5  |       |
| Information Priority|   /5  |       |
| Specificity         |   /5  |       |
| Voice Consistency   |   /5  |       |
| Earned Claims       |   /5  |       |
| **TOTAL**           |  /40  |       |

Pass threshold: 32/40 (all criteria 4+)

Decision Rules

  • All 4+: Copy passes. Minor polish optional.
  • Any 3: Rewrite flagged sections, re-score.
  • Any 2 or below: Full reconstruction required.
  • Multiple failures: Start fresh with new approach.