opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(docs/.style/style-guide): fix self-violating examples (#27849)

Browse Source 
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.
This commit is contained in:
Nick Vigilante
2026-08-04 15:07:05 -04:00
committed by GitHub
parent 87494c4f88
commit 10b366cb7c
2 changed files with 25 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.style/style-guide/accessibility-and-inclusion.md
+11 -11
View File
@@ -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 `<small>` 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 `<small>` 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.
docs/.style/style-guide/formatting.md
+14 -3
View File
@@ -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.