Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs(docs/.style/style-guide): adopt STE-derived prose rules #27852

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nickvigilante merged 2 commits into from
Aug 6, 2026
Merged

docs(docs/.style/style-guide): adopt STE-derived prose rules #27852

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
60d0b1c
docs(docs/.style/style-guide): fix self-violating examples
nickvigilante Aug 4, 2026
a25137c
docs(docs/.style/style-guide): adopt STE-derived prose rules
nickvigilante Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 18 additions & 16 deletions docs/.style/style-guide/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,17 @@ The doctrine for adding Vale rules lives in [`README.md`](../README.md).

## Sections

| Page | Covers |
|-----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Audience and scope](./audience-and-scope.md) | One audience per page; one outcome per page; declare both up front; Coder personas |
| [Voice and tone](./voice-and-tone.md) | Second person; no first-person singular; "we" as the company, not the software; active voice; present tense |
| [Word choice](./word-choice.md) | Canonical brand and product names; "refer to" over "see"; "select" over "click"; weasel words; plain English for product actions; keep internal-only references out of published docs |
| [Accessibility and inclusion](./accessibility-and-inclusion.md) | WCAG target; inclusive pronouns and substitutions; descriptive link text; alt text; page descriptions; heading structure; reading level |
| [Capitalization and punctuation](./capitalization-and-punctuation.md) | Sentence-case headings; no gerund leads; no em-dashes; commas; US-style quotation |
| [Formatting](./formatting.md) | Bold for UI; italics for emphasis; code font for identifiers; language fences on code blocks; callouts; tabs; lists; tables; links; images; screenshots sparingly |
| [Numbers, units, and dates](./numbers-units-and-dates.md) | Digits everywhere; non-breaking space between number and unit; `Month Day, Year` dates; 12-hour time with AM/PM |
| [Editor setup](./editor-setup.md) | Vale editor integration for VS Code, Cursor, JetBrains, and Neovim (placeholder) |
| Page | Covers |
|-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Audience and scope](./audience-and-scope.md) | One audience per page; one outcome per page; declare both up front; Coder personas |
| [Voice and tone](./voice-and-tone.md) | Second person; no first-person singular; "we" as the company, not the software; active voice; present tense; sentence and paragraph budgets; verbs over noun forms; pronoun referents |
| [Procedural writing](./procedural-writing.md) | One instruction per step; condition before instruction; step length; callouts inform, steps instruct; warnings state the consequence |
| [Word choice](./word-choice.md) | Canonical brand and product names; one term per concept; "refer to" over "see"; "select" over "click"; weasel words; plain English for product actions; keep internal-only references out of published docs |
| [Accessibility and inclusion](./accessibility-and-inclusion.md) | WCAG target; inclusive pronouns and substitutions; descriptive link text; alt text; page descriptions; heading structure; reading level |
| [Capitalization and punctuation](./capitalization-and-punctuation.md) | Sentence-case headings; no gerund leads; no em-dashes; commas; US-style quotation |
| [Formatting](./formatting.md) | Bold for UI; italics for emphasis; code font for identifiers; language fences on code blocks; callouts; tabs; lists; tables; links; images; screenshots sparingly |
| [Numbers, units, and dates](./numbers-units-and-dates.md) | Digits everywhere; non-breaking space between number and unit; `Month Day, Year` dates; 12-hour time with AM/PM |
| [Editor setup](./editor-setup.md) | Vale editor integration for VS Code, Cursor, JetBrains, and Neovim (placeholder) |

## Conventions for editing Coder docs

Expand Down Expand Up @@ -103,9 +104,10 @@ The public page is frozen pending the redirect.

When this guide doesn't cover something, consult:

| Type of guidance | Reference |
|--------------------------|-----------------------------------------------------------------------------------------|
| Spelling | [Merriam-Webster](https://www.merriam-webster.com/) |
| Style, nontechnical | [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html) |
| Style, technical | [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) |
| Style, developer-focused | [Google developer documentation style guide](https://developers.google.com/style) |
| Type of guidance | Reference |
|---------------------------|-----------------------------------------------------------------------------------------|
| Spelling | [Merriam-Webster](https://www.merriam-webster.com/) |
| Style, nontechnical | [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html) |
| Style, technical | [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) |
| Style, developer-focused | [Google developer documentation style guide](https://developers.google.com/style) |
| Style, procedural writing | [ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/) (Issue 9, 2025) |
28 changes: 16 additions & 12 deletions docs/.style/style-guide/accessibility-and-inclusion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,31 +166,31 @@ 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.
>
> Open the **Workspaces** sidebar to switch templates.

**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.
>
> Open the menu on the left to switch templates.

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.
Expand Down Expand Up @@ -225,6 +225,10 @@ Replace them with the literal meaning.
>
> Coder ships with a default template out of the box.

The rule covers developer idiom too.
"Spin up a workspace" becomes "create a workspace", "tear down the deployment" becomes "delete the deployment", and "stand up a cluster" becomes "deploy a cluster".
The figurative forms are so common in developer conversation that they no longer register as figurative, but they translate as badly as any other idiom.

*Documentation-only.
Planned Vale rule `Coder.Idioms`.*

Expand Down Expand Up @@ -406,7 +410,7 @@ Aim for a Flesch-Kincaid grade level of 8 to 10 in body prose.
The target supports comprehension for non-native English readers, ESL audiences, and anyone skimming under time pressure.
The reading-level rule decomposes into prose rules covered elsewhere in this guide:

- Short sentences.
- [Short sentences and paragraphs](./voice-and-tone.md#keep-sentences-and-paragraphs-short).
Aim for 25 words or fewer.
- [Active voice by default](./voice-and-tone.md#active-voice-by-default).
- [Present tense by default](./voice-and-tone.md#present-tense-by-default).
Expand Down
17 changes: 14 additions & 3 deletions docs/.style/style-guide/formatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
160 changes: 160 additions & 0 deletions docs/.style/style-guide/procedural-writing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
# Procedural writing

Procedural prose tells the reader what to do: the numbered steps of a how-to guide, a tutorial, or a Quickstart.
The rules on this page govern how instructions, conditions, and callouts behave inside a procedure.
For voice, tense, and sentence-level defaults that apply to all prose, refer to [Voice and tone](./voice-and-tone.md).
For the callout syntax and severity table, refer to [Formatting](./formatting.md#callouts).

Rules adapted from an external standard cite the source so an editor can consult the original rationale.
The source for most of this page is [ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/) (Issue 9, 2025), the controlled-language standard for aerospace and defense maintenance documentation.
STE optimizes for readers who must never misread an instruction.
The Coder docs adopt its procedure-level discipline without its controlled dictionary or its grammar restrictions, which are scoped to a different audience.

## One instruction per step

Each numbered step contains one action.
A reader executes a procedure one step at a time.
A step that bundles two actions invites the reader to complete the first and miss the second.

Two actions belong in one step only when they happen at the same time.

**Do**:

```md
1. Run `coder login`.
2. Paste the session token into the terminal prompt.
```

```md
1. Run `coder port-forward` and leave it running while you test the connection.
```

The second example is one step because the two actions overlap in time.

**Don't**:

```md
1. Run `coder login` and paste the session token into the terminal prompt.
```

The two actions happen in sequence, so they belong in two steps.

*Adapted from ASD-STE100 Issue 9, rule 5.2.
Documentation-only.
No Vale rule.*

## Put the condition before the instruction

When a step applies only under a condition, state the condition first.
The reader acts as they read.
A condition placed after the command reaches the reader after they have started the action.

The same order applies to prerequisites: name the required state before the step that depends on it.

**Do**:

> If the workspace is running, stop it before you push the template.
>
> When the build completes, select **Open in VS Code**.

**Don't**:

> Stop the workspace before you push the template if it's running.
>
> Select **Open in VS Code** when the build completes.

*Adapted from ASD-STE100 Issue 9, rule 5.4.
Documentation-only.
No Vale rule.*

## Keep steps short

Write step sentences of 20 words or fewer.
Body prose gets a 25-word budget (refer to [Keep sentences and paragraphs short](./voice-and-tone.md#keep-sentences-and-paragraphs-short)).
Steps get a tighter budget because the reader is mid-task and holds the instruction in working memory while they act on it.

When a step exceeds the budget, split the sentence, or move background information into the prose around the procedure.
The budget is a target, not a ceiling.
Don't cut words that carry meaning to hit the number.

**Do**:

```md
1. Open **Templates** > **Settings** > **Schedule**.
2. Set the autostop timer to 8 hours.
```

**Don't**:

```md
1. Open the template settings page, find the **Schedule** section, and set the autostop timer to 8 hours so workspaces stop overnight.
```

*Adapted from ASD-STE100 Issue 9, rule 5.1.
Documentation-only.
No Vale rule.*

## Callouts inform, steps instruct

A `NOTE` or `TIP` callout carries supplementary information.
It must not carry a required action, a limit, or an acceptance criterion.
Readers who skim a procedure skip its callouts, so everything the procedure requires must live in a numbered step.

- A required action becomes a step.
- A limit or an expected result goes in the step it validates, directly after the action.
- Information that prevents data loss, downtime, or a security exposure becomes a `WARNING` or `CAUTION`.

To test a procedure, read it with every `NOTE` and `TIP` deleted.
If the reader can no longer complete the procedure correctly, a callout is carrying required content.
Move that content into a step and test again.

**Do**:

```md
1. Back up the database.
2. Run the migration.
```

**Don't**:

```md
1. Run the migration.

> [!NOTE]
> Back up the database before you run the migration.
```

*Adapted from ASD-STE100 Issue 9, rule 5.5.
Documentation-only.
No Vale rule.*

## State the consequence in warnings

A `WARNING` or `CAUTION` callout has two parts: the instruction or condition, then the consequence of ignoring it.
A warning that names no consequence reads as decoration, and the reader cannot weigh a risk the page doesn't name.

**Do**:

```md
> [!WARNING]
> Do not delete the workspace before you back up its state.
> Coder cannot restore a deleted workspace.
```

**Don't**:

```md
> [!WARNING]
> Be careful when you delete workspaces.
```

*Adapted from ASD-STE100 Issue 9, rules 7.2 and 7.3.
Documentation-only.
No Vale rule.*

## Related

- [Style guide landing page](./README.md)
- [Voice and tone](./voice-and-tone.md)
- [Formatting](./formatting.md)
- [Word choice](./word-choice.md)
Loading
Loading