Skip to content

docs: add missing rules from the docs style guide project - #30782

Merged
nickvigilante merged 5 commits into
mainfrom
vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide
Oct 16, 2026
Merged

nickvigilante merged 5 commits into
mainfrom
vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds the style rules from the Docs style guide project (DOCS-1282) that docs/.style/style-guide/ was missing, and fixes the guide's own self-violations and contradictions from the second ASD-STE100 audit (DOCS-1265).
Each new Vale rule lands in its own PR based on this branch, so every footer for those rules reads (planned) here.

Changes

  • New rules: spell out negative instructions (do not, not don't); leave out "please"; how to count words; full clauses instead of -ing clauses in steps; words that have one meaning (ensure, should, may, since); US spelling; noun stacks of three words or fewer; no periods in acronyms; inclusive LGBTQ terms; grandfathered in the inclusive substitutions, with a link to the history of the grandfather clause.
  • Changed rules:
    • The 20-word step budget becomes a firm limit for the whole step, counted per paragraph when a step deliberately breaks into more than one.
    • "Semicolons sparingly" becomes "No semicolons in prose", except in code and table cells.
    • Cross-references use "refer to" or "visit", not "see" or "check out".
    • The whose rule stops recommending "with".
    • Latin abbreviations: prefer the English forms of e.g., i.e., and etc. outside tables, and accept either form.
    • IMPORTANT callouts carry information, never actions.
    • Feature names use title case and instances use sentence case (AI Gateway versus your AI gateway).
    • Literal product text, such as error messages, goes in code spans instead of quotation marks.
  • Vale doctrine: suggestion rules can land with existing findings. Warning and error rules still ship clean.
  • Self-violations: title-case H1, navigational "see", "walkthrough", hard wraps, a British spelling, future-tense promises, the tears down idiom, gerund headings in docs/.style/README.md, semicolons in the DOC3 dash advice, and the numeric-range contradiction.
  • Coverage counts move from 79 to 87 rules, with 9 tool-checked and 33 planned.

Testing

  • go run ./scripts/styleclaims: passes.
  • markdownlint-cli2 and markdown-table-formatter on every changed file: pass.
  • scripts/check_emdash.sh: passes.
  • vale on the changed files that Vale lints (docs/.style/README.md, content-guidelines.md, docs/AGENTS.md): zero findings.
  • Repository pre-commit-light hook: passes.
Decision log

Source

The second ASD-STE100 audit compared the guide with ASD-STE100 Issue 9, and a catalog of the Linear project listed every rule missing from the guide.
Nick reviewed each item and chose to add it, defer it, or edit only the guide.

Decisions

  • All guide text goes in this PR. Each new Vale rule gets its own PR, based on this branch.
  • Vale rule PRs: Coder.Please, Coder.AcronymPeriods (a Coder copy of Google.Periods that also catches 2-letter acronyms), Coder.InclusiveLanguage, Coder.LGBTQ, Coder.USSpelling, Coder.AmbiguousWords (suggestion), Coder.ImperativeNegation, Coder.StepLength, Coder.Semicolons, Coder.CheckOut, Coder.LatinAbbreviations (suggestion).
  • Guide only, because Vale can't detect these: the "with" caution, IMPORTANT callouts, feature versus instance capitalization, and noun stacks. A part-of-speech prototype missed every test stack.
  • Deferred to the backlog: hand-written anchors (DOCS-1278; some are deliberate redirect targets), media captions (DOCS-1279 and DOCS-1286), the noun-stack Vale rule (DOCS-1284), the -ing Vale rule (DOCS-1287), and the product-name Vale rules (DOCS-1285 and DOCS-1288).
  • Imperative negation follows the sentence's mood: "Do not delete the production database" and "Coder won't push the new version" are both correct.
  • Word counting: a code span counts as one word. A bold UI label also counts as one word, which is an assumption for review.

Open for review

  • Literal product text in code spans instead of quotation marks (formatting.md code-font list and the US-style quotation example).
  • Bold UI labels counting as one word.

Generated by Coder Agents on behalf of @nickvigilante.

Add the style rules from the Docs style guide Linear project that the
guide was missing, and fix the guide's own self-violations from the
second ASD-STE100 audit. Each new Vale rule lands in its own PR based
on this one, so every footer for those rules is marked planned.

The Vale doctrine now lets suggestion-level rules land with existing
findings, per Nick's decision on DOCS-450.

Refs DOCS-1282, DOCS-1265
@nickvigilante nickvigilante changed the title docs(docs/.style): add missing rules from the docs style guide project docs: add missing rules from the docs style guide project Oct 14, 2026
@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1282

@nickvigilante
nickvigilante marked this pull request as ready for review October 15, 2026 15:07
@nickvigilante
nickvigilante requested a review from bpmct October 15, 2026 15:08

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

…tyle-guide-add-missing-rules-from-the-docs-style-guide

# Conflicts:
#	docs/.style/style-guide/README.md
@nickvigilante
nickvigilante merged commit c4cfe8a into main Oct 16, 2026
29 of 30 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 16, 2026
@nickvigilante
nickvigilante deleted the vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide branch October 16, 2026 13:53
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants