---
title: "Voice and Tone"
slug: "voice"
category: "writing"
tags: ["writing", "voice", "style"]
status: "stable"
last_updated: 2026-05-14
summary: "Neutral playbook voice: lead with the rule, name the thing, vary rhythm. The voice every page on this site uses."
related: ["[[writing/anti-slop]]", "[[writing/articles]]", "[[writing/editorial-style]]", "[[writing/headlines]]"]
---

## Overview

Voice on this site is neutral playbook. The reader (human or agent) wants the rule; rationale earns its place after the rule is on the page. This is the short-form voice spec. For specific constructions to avoid, see [[writing/anti-slop]].

## Lead with the rule

Open every section, every paragraph, and most sentences with the rule itself.

- "Use Postgres for app data." Not "Postgres is generally considered a good choice for app data."
- "Avoid `@apply`." Not "Many developers find `@apply` problematic in certain cases."

Once the rule is on the page, give the rationale in the next clause or sentence.

## Name the thing

Specific nouns. Specific versions.

- "Postgres 17," not "modern relational databases."
- "Cloudflare Workers," not "edge functions."
- "`pg_dump --jobs=4`," not "Postgres's parallel backup tool."

If a sentence still reads when you remove a category word ("solution," "approach," "technology"), delete it.

## State the rationale once

A rule's rationale lives in its first appearance. Do not restate it three sections later. If a downstream rule depends on the same reasoning, link back: "See the rationale in [[backend/postgres]]."

## Vary rhythm

A page of identical-length sentences sounds like a model. Mix lengths.

- Do not follow a long sentence with another long sentence.
- Do not stack three short sentences unless the staccato is doing real work.
- Read a paragraph aloud. If you run out of breath, cut it.

## Confidence over hedges

Pick a side. Hedge only when the rule genuinely has exceptions, and name those exceptions.

- "Use SQLite for single-writer workloads." Not "SQLite might be a reasonable choice in some cases."
- "Prefer Postgres over MySQL." Not "Both Postgres and MySQL have their merits."

A page that hedges every claim is unusable.

## Examples carry the weight

When a rule is non-obvious, show code or a before-and-after pair.

```ts
// Bad
const x = items.filter((i) => i.active).map((i) => i.id)

// Better
const activeIds = items.filter((i) => i.active).map((i) => i.id)
```

See [[writing/anti-slop]] for the rewrite pattern applied to prose.

## Forbidden vocabulary

A short list. The full list lives in [[writing/anti-slop]].

- No `"delve,"` `"dive in,"` `"navigate the landscape of,"` `"unlock."`
- No `"leverage"` as a verb.
- No `"robust solutions,"` `"comprehensive guide,"` `"seamless experience."`
- No em-dashes for parenthetical asides.

## Tone register

Direct, not curt. Confident, not boastful. Helpful, not chummy.

- Prefer the imperative ("Use," "Avoid") when the rule applies to anyone touching the codebase.
- Use "you" when addressing the reader's specific decision ("If you are on Vercel, set the framework preset to Astro").
- Avoid "we" unless writing co-authored material.

## Related

- [[writing/anti-slop]]
- [[writing/articles]]
- [[writing/editorial-style]]
- [[writing/headlines]]