The style contract
How to get consistent docs out of an LLM without pasting a new example every time.
The problem you already have
Most of us draft docs the same way now. You open a chat, paste a topic or a rough draft, add one good example, and say “write like this.” It works. Once.
The next day you pick a different example. A teammate picks another. Three weeks later your docs read like five people wrote them, because they did. A style contract fixes that: you write the style down once, as a short spec the model reads before it writes, and it follows that spec every time.
Four levels, most days you live in two
Paste and pray
One example, pasted fresh each time. Fast, and it drifts. This is where most teams are.
A style contract
You write the style down once, as a short spec the model reads before it writes.
Automate it
You save the contract so you stop re-pasting: a Claude Project or custom GPT, or a STYLE.md in the repo your whole team points to.
The hard part
Making the output trustworthy: grounded in the source, reviewed, safe to ship. That is a separate and harder problem. This note stays at Levels 1 and 2, where the daily pain lives.
The template
Copy this, fill the brackets, and paste it above your source. Keep it to one screen.
# Style contract: [product or doc set]
Audience: [who reads this, and their expertise]
Reading level: [e.g. plain, roughly grade 8 to 10]
Voice: [3 to 5 adjectives, e.g. direct, calm, concrete]
Do:
- [e.g. lead with the task, then the detail]
- [e.g. write the number inside a full sentence]
Don't:
- [e.g. no marketing adjectives]
- [e.g. no walls of text; break work into steps]
Formatting:
- Headings: [e.g. sentence case]
- Multiple cases or options: [e.g. a table]
- Steps: [e.g. numbered list, one action per step]
Terminology:
- Prefer: [term], [term]
- Never: [term], [term]
Default shape for a task: [e.g. goal, prerequisites, steps, result]
Gold example (match this):
[paste one short, real, approved doc]A filled example
So it is concrete. This is a made-up product, written fresh, with nothing from any employer.
# Style contract: Acme CLI docs
Audience: backend developers, comfortable with a terminal, new to Acme
Reading level: plain, roughly grade 9
Voice: direct, calm, concrete
Do:
- lead with what the command does, then how to run it
- show one runnable example per command
Don't:
- no "simply", "just", "easily"
- no paragraph longer than four lines
Formatting:
- Headings: sentence case
- Flags and options: a table with Flag, Type, Description
- Steps: numbered, one action each
Terminology:
- Prefer: "run", "flag", "endpoint"
- Never: "hit the API", "spin up", "utilize"
Default shape for a task: goal, prerequisites, steps, expected output
Gold example (match this):
## Set your API key
Acme reads your key from the ACME_KEY environment variable.
1. Copy your key from the dashboard.
2. Export it: export ACME_KEY=your_key
You should see: "Key accepted."Automate it (Level 2)
Three ways, one idea. Pick the one your team already lives in.
1. A Project or custom GPT
Paste the contract into the project instructions once. Every chat in that project already knows your style.
2. A STYLE.md in the repo
Commit the contract as STYLE.md and tell the model “follow STYLE.md.” The style is versioned, reviewed in pull requests, and identical for every writer.
3. A saved snippet
Keep it in a text expander or a pinned note. Low tech, and it still works.
The 60-second self-check
Run this before you ship the doc.
- Reading level. Could a new hire read it without a glossary?
- Terminology. Same words for the same things, every time?
- Formatting. Headings, tables, and lists per the contract?
- Banned words. None slipped back in?
- Structure. Does it follow the default shape?
- Gold example. Put them side by side. Same writer?
One honest limit
Consistency is what this buys
An LLM will follow your style beautifully while stating something subtly wrong, out of date, or unsafe to publish. A style contract covers voice and format. Correctness is a separate job.
Catching that is the harder problem: grounding, review, and governance. It is the real work behind trustworthy AI-assisted docs, and it is a longer conversation. This note is the easy, high-value first step. Take it, copy it, and tell me what breaks: write@elizamarin.com.