---
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 source, or cut it.
- **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.