Files
coder/docs/AGENTS.md
Nick Vigilante 21471da74c feat: enable Coder.Semicolons Vale rule (#30787)
Depends on #30782.

Adds `Coder.Semicolons`, a Vale rule that flags a semicolon in prose.
It enforces [No semicolons in
prose](https://github.com/coder/coder/blob/main/docs/.style/style-guide/capitalization-and-punctuation.md#no-semicolons-in-prose).

- Severity: `warning`.
- Scope: paragraphs, list items, headings, and blockquotes in `docs/**`
except `docs/.style/style-guide/**`.
  Table cells, code spans, and code blocks keep their semicolons.
- Baseline: 137 findings.
The cleanup commit fixes 112 of them across 61 files by splitting
sentences, or by using a comma or a connecting word where a split reads
badly.
- Excluded in `.vale.ini`: `docs/reference/{api,cli}/*.md` and
`docs/admin/setup/configuration-reference.md`.
Their text is generated from Go source (CLI flag help, Swagger
comments), and 25 findings live there.
Fixing them means editing Go and regenerating, so I used a commented
exclusion like `Coder.UnitSpacing` does.
  Say so if you prefer the Go fix.
- Result: `vale --output=line docs/` reports 0 `Coder.Semicolons`
findings outside the style guide.
- Three headings lost a semicolon, so their anchors changed.
I updated the links in `docs/.style/` and in `.claude/`
(`DOCS_STYLE_GUIDE.md`, the `write-docs` and `doc-check` skills).

Linear: DOCS-1261

<details><summary>Decision log</summary>

- Scope list is `paragraph`, `list`, `heading`, `blockquote`. Without
`blockquote`, a semicolon in a `>` quote goes unreported, which I
checked.
Table cells are outside those scopes, so they stay exempt without extra
config.
- Token is `(?<!TL);(?!DR)`. `TL;DR` in `telemetry.md` is an
abbreviation, not punctuation.
- `&nbsp;` entities and `style="a: b;"` attributes don't match. Vale can
report a real semicolon on the wrong line of a paragraph that contains
an entity or raw HTML (for example, `modules.md:69` pointed at a
semicolon on line 71), so cleanup used a paragraph-wide search instead
of trusting reported lines.
- A semicolon inside a fenced block in a blockquote
(`ai-gateway/monitoring.md:105`, a YAML comment) isn't reported and
stays.
- Cleanup default: `; x` becomes `. X`, then I reviewed the diff and
hand-fixed list fragments, parentheticals, and headings.
Each new sentence sits on its own line, outside table cells. The
hand-written part of `prometheus.md` is also reformatted to one sentence
per line.
- Heading rewrites: `Verify against the code and document exact values`,
`Evidence justifies a claim and does not belong in the claim`, `STUN
returned different addresses and you may be behind a hard NAT`.
- `prometheus.md` is in the generated-page exclusion for
`Coder.UnitSpacing` but not here. Its semicolon was in hand-written
prose, so I fixed it.
- Enable commit updates the footer, the checks table (scope text matches
`.vale.ini`), the coverage counts (Capitalization and punctuation 3/7 to
4/6, total 20 to 21 tool-checked and 25 to 24 planned), and the "What
the tooling checks" counts.

Tests (fixtures in `/tmp`, not committed), each run with LF and CRLF
files:

- Flagged: paragraph, list item, ordered list item, heading, blockquote.
- Not flagged: table cell, code span, fenced block, `&nbsp;` and
`&amp;`, an HTML `style` attribute, and `TL;DR`.
- `go run ./scripts/styleclaims`, `make lint/emdash`, and the pre-commit
hook (markdown, typos, style-claims) pass.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*
2026-10-27 16:44:17 +00:00

4.0 KiB

Documentation Guidelines

Read the style guide before you write docs prose. It is the canonical source. This page is the short list of rules that get missed most often.

The surrounding page is not a reliable guide to house style. Most of the corpus predates these rules, so match the rules, not the neighboring lines.

When the style guide and the content guidelines conflict, the content guidelines govern scope and routing.

Docs contract

  • DOC1: One sentence per source line. Do not split a sentence across lines, and do not wrap to a fixed column width. MD013 is disabled on purpose.
  • DOC2: Headings are sentence case, don't lead with an -ing word, and carry no trailing punctuation.
  • DOC3: No em-dashes, en-dashes, or -- as punctuation, in prose, code, comments, or strings. Use commas, parentheses, periods, or a restructured sentence, not semicolons.
  • DOC4: Address the reader as "you". No first-person singular. Reserve "we" for Coder Technologies as a company.
  • DOC5: Active voice, present tense, contractions by default. Spell out negative instructions: do not, not don't. Keep sentences short, and keep each step to 20 words or fewer.
  • DOC6: Use the canonical term: select not click, stop not kill, turn off not disable, refer to or visit not see or check out, Learn more not Next steps, tutorial not walkthrough.
  • DOC7: Use canonical product and brand casing, and one term per concept.
  • DOC8: One instruction per step. Put the condition before the instruction. Callouts inform, steps instruct, and a warning states its consequence.
  • DOC9: Link text and alt text describe the destination or the image. Never here or click here.
  • DOC10: One audience and one outcome per page, declared up front.
  • DOC11: Digits for 6 and higher, a non-breaking space between a number and its unit, and the documented date and time formats.

Commands

Task Command
Prose lint (Vale) make lint/prose
Markdown lint pnpm run check-docs
Markdown fix pnpm run lint-docs
Table format pnpm run format-docs

Prettier does not own Markdown in this repository. Do not run it over docs/.

Where the rules live

Topic Page
Line breaks, text formatting, block elements formatting.md
Headings, dashes, commas, quotes capitalization-and-punctuation.md
Person, voice, tense, sentence length voice-and-tone.md
Terminology and banned words word-choice.md
Steps, conditions, callouts procedural-writing.md
Link text, alt text, plain English accessibility-and-inclusion.md
Audience, scope, personas audience-and-scope.md
Numbers, units, dates numbers-units-and-dates.md
What belongs in docs/ at all content-guidelines.md

Vale enforces a subset of these rules and reports the rest as advisory annotations. A clean make lint/prose run does not mean the prose follows the style guide.