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.