Agent-authored docs PRs kept leaking implementation detail into user-facing pages: chat status enum values and `root_chat_id` on the auto-archive page (#28570, flagged by reviewers), and RBAC resource names and response fields in the first revision of #28482. The correction pattern was the same each time: state the behavior in the reader's terms. This encodes that pattern as one canonical rule with citations in every file that carries the exact-values instruction: - `docs/.style/content-guidelines.md`: new guiding principle "Evidence justifies a claim; it does not belong in the claim". The test is scoped to the task the page documents, with a first-match ladder: exact value where the reader types or receives it, visible product wording where the screen shows it, plain reader's-terms prose otherwise. An identifier set described as a set resolves at the lowest rung any member reaches. Stripped identifiers are named (file and symbol) in the PR discussion as a best-effort pointer for the reviewer. Cross-linked with verify-exact-values, describe-current-version, the routing table, and word-choice. Also repairs a pre-existing broken feature-stages link. - `docs/.style/style-guide/word-choice.md`: the internal-references section notes that implementation identifiers follow the (conditional) canonical rule, covering the prose-edit route that AGENTS.md sends to the prose style guide. - `.claude/docs/DOCS_STYLE_GUIDE.md`: the Accuracy Standards section head and Key Principles item 2 carry the same qualifier, since this always-loaded file is where agents get the unqualified exact-values instruction. - `.claude/skills/write-docs/SKILL.md`: workflow step 1 marks copied identifiers as verification inputs with a forward link; citation-only "Evidence versus claim" section; matching anti-pattern bullet and a checklist item that defers the stripped-identifier disclosure to the canonical rule. - `.claude/skills/doc-check/SKILL.md`: "Evidence versus claim" check scoped to identifiers the change adds or touches, working from the diff (doc-check does not police the disclosure, which it cannot see); pre-existing violations on untouched pages are informational only. The motivating page (`chat-auto-archive.md`) was fixed separately in #28570 (DOCS-722, merged). Corpus sweep for other violations: DOCS-730. Lint and link coverage for the `.claude` and `docs/.style` trees: DOCS-729. Linear: DOCS-728 https://linear.app/codercom/issue/DOCS-728 <details> <summary>CI note (docs-only PR)</summary> This PR changes only Markdown under `docs/.style/` and `.claude/` (no `site/src` or other product code). - The `ci` workflow's docs-relevant jobs pass on the head commit: `changes`, `gen`, `lint`, `lint-docs`, `fmt`, `offlinedocs`, `required`. Heavy build/test jobs are correctly skipped for a docs-only change. (Run: https://github.com/coder/coder/actions/runs/32986743037) - `Pixel / Review` (frontend visual snapshots) is unrelated to the changed paths and is treated as an unrelated flake. </details> > This PR was created with AI assistance (Coder Agents).
docs/.style/
Contributor-facing style and content guidance for the Coder documentation. Nothing under this directory is published to coder.com/docs.
What lives here
| Path | Purpose |
|---|---|
content-guidelines.md |
Canonical content rules: what belongs in docs/, what doesn't, why |
style-guide/ |
Canonical prose style guide for docs/ |
styles/Coder/ |
Custom Vale rules specific to Coder (product voice, terms) |
Refer to content-guidelines.md for the canonical rules on what content belongs in docs/ and what should be routed elsewhere (blog, changelog, Support KB, etc.).
Visit style-guide/ for the prose style guide.
The styles/Coder/ directory holds the custom Vale rules that enforce parts of the guide; Vale's StylesPath in the repo-root .vale.ini points at docs/.style/styles/.
Why a hidden directory
The leading dot mirrors the .github/, .vscode/, and .claude/ convention already used in this repo for tooling-internal directories.
The structural Markdown linters and Vale still pick it up (except the style guide's own prose under style-guide/, which is exempt); coder.com's docs site does not.
Refer to "What does not run against this directory" below for that exemption.
How exclusion from coder.com works
coder.com/docs routes and search are manifest-driven:
- Route discovery lives in
coder/coder.com:src/utils/docs/docs.ts(getDocsStaticPaths). It iteratesroutesfromdocs/manifest.jsonand emits one Next.js static path per entry. Files not in the manifest do not become routes. - The Algolia surgical indexer at
coder/coder.com:src/utils/algoliaDocs/surgical.tsexplicitly skips paths that are not in the manifest, incrementingpathsSkipped.
Net result: not adding anything from docs/.style/ to docs/manifest.json gives us no route, no Algolia record, and no sidebar entry.
Two defense-in-depth changes in .github/workflows/deploy-docs.yaml keep the deploy workflow from running on .style-only commits and exclude the directory from the surgical-reindex payload on mixed commits.
What still runs against this directory
make lint/markdown(markdownlint-cli2) processes every Markdown file here. The repo-rootpackage.jsoninvokesmarkdownlint-cli2 --fix $(find docs -name '*.md').make fmt/markdown(markdown-table-formatter) reflows tables here for the same reason.- Vale (
make lint/prose) lints everything here except the style guide's own prose understyle-guide/: the landing page,content-guidelines.md, the annotation demo (whoseCoder.Demo*rules are meant to fire), and the Coder rule docs. Refer to the repo-root.vale.inifor the active configuration, and to "What does not run against this directory" below for the one exemption.
What does not run against this directory
linkspector: excluded viaexcludedDirsin.github/.linkspector.yml. External-link checking is overkill for contributor tooling.- The
deploy-docsworkflow: itspaths:filter negatesdocs/.style/**, and the surgical-reindex git-diff invocation excludes the same path. See.github/workflows/deploy-docs.yaml. - The
docs-previewworkflow: itspaths:filter negatesdocs/.style/**, so.style-only PRs produce no preview comment. The selection logic also skips.stylefiles when picking the preview target on mixed PRs. See.github/workflows/docs-preview.yaml. - Vale's
Coderrules on the style guide's own prose underdocs/.style/style-guide/. The guide deliberately contains the constructs the rules ban, such as Don't examples and banned terms named in headings and prose, so the repo-root.vale.iniclearsBasedOnStylesfordocs/.style/style-guide/**. Nothing else underdocs/.style/is exempt: the landing page,content-guidelines.md, the annotation demo, and the Coder rule docs are all linted. Zero-baseline is therefore measured overdocs/excludingdocs/.style/style-guide/. The exemption applies only when the path resolves todocs/.style/style-guide/...from the working directory, which is whatmake lint/proseand CI pass (repo-root-relativedocs/...). Other invocation forms bypass the glob and still flag the guide's intentional examples: absolute paths (what editors and LSP integrations pass) and subdirectory-relative paths (for examplevale .style/style-guide/...run fromdocs/). Treat those in-editor and subdirectory findings on the guide as expected.
Editing the content guidelines
Open a PR against docs/.style/content-guidelines.md.
The rules in that file apply to humans and AI-assisted workflows alike; when it conflicts with another style or contributing doc in the repo, it governs.
Editing the style guide
Open a PR against the appropriate subpage of docs/.style/style-guide/.
Follow-up PRs add each rule and the matching style-guide section together.
Adding a Vale rule
Each rule in the repo-root .vale.ini ships clean: zero baseline findings against the current docs/ corpus, excluding docs/.style/style-guide/, which is exempt because the style guide demonstrates the violations the rules ban.
The PR that adds a rule is the rule's complete unit:
- Cleanup commit: fix every existing-content violation of the new rule so
make lint/prosereports zero findings for it. The cleanup ships in the same PR as the enable, ordered first. - Enable commit: add the rule to
.vale.iniat its chosen severity, write a corresponding section under the matching subpage ofdocs/.style/style-guide/, and add the custom rule YAML underdocs/.style/styles/Coder/if applicable. The rule'smessage:field points at the relevant style-guide subpage anchor.
Severity is a deliberate per-rule choice:
errorblocks merge. Use for hard policy where any violation is wrong: brand-name casing, first-person pronouns we ban outright, em-dash bans.warningsurfaces an annotation without failing CI. Use for strong guidance with legitimate human-judgment exceptions: terms that need context (disabledas a technical state vs. ableist usage), judgment-bound style preferences.suggestionsurfaces anoticeannotation. Use for soft guidance where the right fix is contextual: noun-as-adjective patterns likedesired state, wordiness, optional sentence reshaping.
The severity choice and the cleanup discipline are independent.
A rule landing at warning or suggestion still ships with zero baseline findings; the rule's purpose is to catch new violations, not to surface a backlog of existing ones.
A rule that surfaces a standing backlog teaches contributors to ignore the annotation channel, which erodes trust in CI regardless of the severity at which the noise arrives.
PR title: feat(docs/.style): enable <RuleName>.
False-positive policy: one confirmed false positive after enable, either refine the rule or revert. We do not maintain rules that occasionally cry wolf, regardless of severity.
If a policy is judgment-bound (passive voice, weasel words, sentence-case headings on a corpus with many proper nouns), write a Coder-authored rule with the precision the situation needs instead of accepting an imprecise third-party rule at any severity.
This applies equally to Coder-authored rules (under docs/.style/styles/Coder/) and third-party rules from Google, alex, and write-good.
Third-party rules are not loaded by default.
Each returns through the same per-rule PR pattern after its corpus is clean.