---
name: docs-team-voice
description: Write or revise documentation prose so it reads like the rest of this site, in the docs team's shared voice. Covers sentence length, cross-link density, how to state defaults and conditions, naming exact identifiers, and what to cut in a revision pass. Use when drafting or rewriting a page, a section, a concept overview, a how-to, a callout, or landing copy.
---
# Write in the house voice
`AGENTS.md` holds the rules a linter can check: no contractions, no first
person, no future tense, sentence-case headings, Oxford commas, spacing around
dashes. Vale enforces most of them and `make lint_prose` is the gate, though
Vale does not scan inside JSX components such as `<Note>` and `<Tip>`, so a
clean run there proves nothing. This skill covers what a linter cannot check:
rhythm, density, and the shape of a sentence that carries information.
The targets below are measured from this repository's own pages, not invented.
## Keep sentences short
Median sentence length on this site is **13 to 15 words**. Roughly one sentence
in twelve runs past 25 words, one in forty past 30. Treat 25 as the point where
you look for a split and 35 as a defect.
One idea per sentence. When a sentence carries two, split it and let the second
stand alone.
> The agent definition selects the model and core capabilities of a managed deep
> agent.
> Set the `compression` field to control how exported Parquet files are
> compressed. When omitted, LangSmith uses `zstandard`.
The second example is two sentences where one long one would have hidden the
default inside a subordinate clause.
The target is a floor as well as a ceiling. Keep the condition, the actor, and
the exact value even when they push a sentence long, and split it rather than
dropping one of them to get under 15 words.
## Link about half the time
Close to half of all prose sentences here carry a link. Cross-linking is not
decoration: it is how a reader escapes a page that does not answer the question
they arrived with.
Link a term on first mention only. Pointing forward at the end of a section is
standard, and **two pointer forms are both established**:
> Refer to [Spend policies](/langsmith/llm-gateway-spend-policies).
> For the full project layout, see [Project
> structure](/langsmith/managed-deep-agents-project-structure).
Neither is canonical. Different authors favor different ones, so match the form
the page already uses and do not mass-convert one into the other.
## State defaults and conditions as bare facts
Put the trigger first, then the behavior. No hedging, no "please note".
> When omitted, LangSmith uses `zstandard`.
> Defaults to the last 7 days, newest first.
> Task planning is opt-in.
> Non-zero exits and timeouts from `--startup-cmd` warn but do not abort the
> session.
Constraints read the same way, as plain statements of fact rather than warnings
about them.
## Name the exact identifier
Backtick every field, flag, value, environment variable, and status. Between a
quarter and a half of prose sentences on this site contain one. Name the actual
value rather than gesturing at it: `zstandard`, not "the appropriate
compression"; `CREATED`, `RUNNING`, `COMPLETED`, not "the various statuses".
> If your API key is linked to multiple workspaces, specify the workspace in the
> header with `"x-tenant-id"`.
## Reach for a concrete example early
"For example" appears in roughly one sentence in thirty, almost always followed
by a real value rather than a shape.
> For example, in SCIM, the resolved `sub` claim and SCIM `externalId` must
> match in order for login to succeed.
If you cannot supply a real example, say less rather than inventing one. Never
fabricate a field name, a response body, or a policy detail to fill a slot.
## Address the reader, and prefer the active voice
Second person carries a quarter to a half of sentences, most heavily in
procedures and UI steps. Passive voice appears in only about one sentence in
eight, and usually where the actor genuinely does not matter.
> When viewing a trace that was generated by a run in LangSmith, you can access
> the associated server logs directly from the Details view.
Use the product name as the subject when the reader is not the actor: "LangSmith
uses `zstandard`", not "we use `zstandard`".
## Revision pass
Read the draft once looking only for these:
- **Sentences over 25 words.** Split, or cut a clause.
- **Hedges and filler.** "simply", "just", "very", "basically", "note that",
"be sure to", "in order to", "has the ability to". These are near-absent from
this site's prose, well under one percent of sentences. Delete or replace.
- **A spaced em dash.** `word — word` fails `LangChain.DashesSpaces` and blocks
CI. Prefer a comma, a colon, or two sentences, and reach for `word—word` only
when nothing else reads. A bold label opening a paragraph takes a colon:
`**Tier assignment**:`, measured at 177 uses in `src/` against 1 for the dash.
- **A vague identifier** where the exact one belongs.
- **A cut that took a fact with it.** A tightened sentence that lost its
condition, its actor, or its exact value reads cleanly and says something
else. Restore the fact and split the sentence.
- **A first mention with no link**, and repeat mentions that are linked again.
- **A claim you did not verify.** Check it against the product source with the
`verify-against-source` skill, or cut it. Another docs page is not a source.
Name every claim you could not confirm in the PR body.
- **A fact that disagrees with a related page.** Grep `src/` for the feature and
read the pages that cover it from another angle, such as a CLI reference or a
permissions table. The `docs-edit` skill covers what to look for.
- **An added "key features" list, or a horizontal rule** used to separate
sections. Neither belongs here.
Then run the gate:
```bash
make lint_prose FILES="<changed files>"
```
For a full review against the style guide, with the rule each finding breaks,
use the `docs-review` skill.