Docs Team Voice

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.

For the full project layout, see 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.