From 10b366cb7c49252c2b3ef9a72b050663c94a4bae Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Tue, 4 Aug 2026 15:07:05 -0400 Subject: [PATCH] docs(docs/.style/style-guide): fix self-violating examples (#27849) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two internal-consistency fixes in the prose style guide, found while auditing it against ASD-STE100 (Simplified Technical English). The directional-language section in `accessibility-and-inclusion.md` used "See the [Latin abbreviations rule]" as a **Do** example and recommended "see the following section" in its replacements table. Both violate the navigational-"see" ban that `word-choice.md` applies to all docs, so the examples now use "refer to". The one-sentence-per-line **Do** and **Don't** examples in `formatting.md` were byte-identical single source lines, so the **Don't** examples demonstrated no violation. Blockquotes re-join lines when rendered, which is why the broken examples went unnoticed. The examples are now fenced `md` blocks that show the actual source line breaks (clause breaks and fixed-column wrap). --- 🤖 Built with AI assistance. --- .../accessibility-and-inclusion.md | 22 +++++++++---------- docs/.style/style-guide/formatting.md | 17 +++++++++++--- 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/docs/.style/style-guide/accessibility-and-inclusion.md b/docs/.style/style-guide/accessibility-and-inclusion.md index 761a0ad23c..8074b769a7 100644 --- a/docs/.style/style-guide/accessibility-and-inclusion.md +++ b/docs/.style/style-guide/accessibility-and-inclusion.md @@ -166,7 +166,7 @@ Refer to UI elements by their label, not by their position on the screen. **Do**: -> See the [Latin abbreviations rule](#latin-abbreviations) for the comma convention. +> Refer to the [Latin abbreviations rule](#latin-abbreviations) for the comma convention. > > Add a `` caption after the image. > @@ -174,7 +174,7 @@ Refer to UI elements by their label, not by their position on the screen. **Don't**: -> See the table below for the comma convention. +> Refer to the table below for the comma convention. > > Add a `` caption underneath the image. > @@ -182,15 +182,15 @@ Refer to UI elements by their label, not by their position on the screen. Common replacements: -| Avoid | Prefer | -|------------------------------|---------------------------------------------------------| -| see below | see the following section, see the `[Section](#anchor)` | -| see above | see the previous section, see earlier | -| top of the page | beginning of the page | -| bottom of the page | end of the page | -| the menu on the left | the **Sidebar** menu | -| the right side of the screen | the **Details** panel | -| scroll down | scroll to the `[Section](#anchor)`, scroll to the end | +| Avoid | Prefer | +|------------------------------|-------------------------------------------------------------------| +| see below | refer to the following section, refer to the `[Section](#anchor)` | +| see above | refer to the previous section, as described earlier | +| top of the page | beginning of the page | +| bottom of the page | end of the page | +| the menu on the left | the **Sidebar** menu | +| the right side of the screen | the **Details** panel | +| scroll down | scroll to the `[Section](#anchor)`, scroll to the end | The rule covers prose. Idiomatic stack metaphors like "built on top of Terraform" and phrasal verbs like "set up", "back up", "log in", and "shut down" aren't directional and stay as-is. diff --git a/docs/.style/style-guide/formatting.md b/docs/.style/style-guide/formatting.md index 9d2ce3df79..e77d89289c 100644 --- a/docs/.style/style-guide/formatting.md +++ b/docs/.style/style-guide/formatting.md @@ -27,17 +27,28 @@ What doesn't get its own line: - Source inside fenced code blocks, where the language's own conventions apply. - Table rows, which are governed by `markdown-table-formatter`. +The examples show Markdown source, not rendered output, because the convention governs how the source lines are laid out. + **Do**: -> The Coder agent connects to the workspace, opens a Tailscale tunnel, and forwards SSH and IDE traffic over the tunnel. +```md +The Coder agent connects to the workspace, opens a Tailscale tunnel, and forwards SSH and IDE traffic over the tunnel. +``` **Don't** (mid-sentence clause breaks): -> The Coder agent connects to the workspace, opens a Tailscale tunnel, and forwards SSH and IDE traffic over the tunnel. +```md +The Coder agent connects to the workspace, +opens a Tailscale tunnel, +and forwards SSH and IDE traffic over the tunnel. +``` **Don't** (fixed column wrap): -> The Coder agent connects to the workspace, opens a Tailscale tunnel, and forwards SSH and IDE traffic over the tunnel. +```md +The Coder agent connects to the workspace, opens a Tailscale +tunnel, and forwards SSH and IDE traffic over the tunnel. +``` Both **Don't** versions add noise to the source and produce diff churn on small edits.