docs(docs/.style/style-guide): fix self-violations found by audit - #27855
Merged
Conversation
Run every style guide page through the guide's own rules, including
the STE-derived rules added in the previous commit, and fix the
violations in the guide's prose and Do examples. Don't examples keep
their intentional violations. Highlights:
- Objective defects: an unbalanced quotation mark, a stale "this PR"
reference, a mangled console Do example, inline "[!NOTE]" markers
that GitHub renders as literal text, "a onClick", and stale Vale
rule references (write-good.Reading, Google.Ordinal).
- A Do example on the audience page used the exact metadata line the
same page bans; a Do example on the word-choice page had Coder
running its own login command.
- US-style quotation: commas and periods moved inside closing quotes
throughout the guide's own prose.
- Banned vocabulary in guide prose: navigational directionality
("above"), idioms ("wall of", "silently rots", "when in doubt",
"stretch goal", "bleeding-edge", "put up with"), simplicity words
("easy", "straightforward", "clearly"), and vague qualifiers
("typically", "almost always", "often", "rarely").
- Structure: framing paragraphs under bare headings, one sentence per
source line for run-in bold leads and split example sentences,
prose semicolons split into sentences, 6-item prose enumerations
reduced or split, and long sentences brought under the budget.
- Heading consistency: end-of-page "Related" sections renamed to
"Learn more" to match the guide's own heading rule.
- Policy clarification, flagged for docs-team review: the
digits-everywhere rule now scopes out numbers that describe
language itself and "one" as a determiner or pronoun, and the
remaining prose converts real counts to digits.
Assisted-by: AI
nickvigilante
force-pushed
the
style-guide-self-audit
branch
from
August 14, 2026 17:15
79a55fd to
6c56017
Compare
nickvigilante
marked this pull request as ready for review
August 14, 2026 17:18
matifali
approved these changes
Aug 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Builds on #27849 and #27852 (both merged).
Runs every style guide page through the guide's own rules, including the STE-derived rules from #27852, and fixes the violations in the guide's prose and Do examples. Don't examples keep their intentional violations. Three parallel audit passes produced roughly 120 findings; this PR applies the accepted ones.
Objective defects fixed: an unbalanced quotation mark on the audience page, a stale "in this PR" reference in the README, a
consoleDo example whose command and output had been collapsed onto one line, inline> [!NOTE]markers that GitHub renders as literal text instead of callouts, "aonClick", and two stale Vale rule references. Two Do examples modeled banned or wrong prose: the audience page's example contained the exact*Audience: ...*metadata line the same page bans, and a word-choice example had Coder running its own login command.Rule-adherence fixes: US-quotation comma/period placement throughout, banned idioms and figurative language ("wall of commas", "silently rots", "when in doubt", "stretch goal", "bleeding-edge", the Churchill "put up with" example), simplicity words and vague qualifiers ("easy", "straightforward", "typically", "almost always", "often"), directional "above", framing paragraphs under bare headings, run-in bold leads split to one sentence per source line, prose semicolons split into sentences, 6-item prose enumerations reduced, and end-of-page "Related" sections renamed to Learn more per the guide's own heading rule.
One policy call for docs-team review: the digits-everywhere rule now scopes out numbers that describe language itself ("a contraction joins exactly two words") and
oneas a determiner or pronoun. The alternative was rewriting every determiner as a digit ("give each paragraph 1 topic"), which makes the prose worse. With the scoped rule, the remaining real counts were converted to digits.Deliberately not changed: "lands"/"land" as release vocabulary, attributed claims inside the Latin-abbreviations `` block, persona-sketch color on the audience page (writer-facing planning vocabulary), and the "What's a workspace" heading example.
Linear: DOCS-650