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.

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:

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.