--- 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 `` and ``, 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="" ``` For a full review against the style guide, with the rule each finding breaks, use the `docs-review` skill.