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. - ` ` 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, ` ` and `&`, 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.*
4.0 KiB
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.
MD013is disabled on purpose. - DOC2: Headings are sentence case, don't lead with an
-ingword, 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, notdon't. Keep sentences short, and keep each step to 20 words or fewer. - DOC6: Use the canonical term:
selectnotclick,stopnotkill,turn offnotdisable,refer toorvisitnotseeorcheck out,Learn morenotNext steps,tutorialnotwalkthrough. - 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
hereorclick 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.