LLM Best Practices

Voice and Tone

3 min read

View markdown source

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 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 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.

// 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 anti-slop for the rewrite pattern applied to prose.

Forbidden vocabulary

A short list. The full list lives in 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.

Graph View

Backlinks