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): adopt STE-derived prose rules (#27852)

Browse Source 
Stacked on #27849.

Incorporates the transferable rules from [ASD-STE100 Simplified
Technical English](https://www.asd-ste100.org/) (Issue 9, 2025) into the
prose style guide, with per-rule attribution to the source rule numbers.
STE is the controlled-language standard for aerospace maintenance
documentation; this PR adopts its procedure-level discipline and clarity
rules, not its controlled dictionary or grammar restrictions, which
target a different audience.

- New **Procedural writing** page: one instruction per step, condition
before instruction, 20-word step budget, "callouts inform, steps
instruct" (with the delete-the-callouts test), and warnings must state
the consequence.
- **Voice and tone**: sentence and paragraph budgets, verbs over noun
forms, one clear referent per pronoun, and an explicit acknowledgment of
the contractions trade-off for international readers.
- **Word choice**: one term per concept, anchored on the glossary.
- **Accessibility and inclusion**: the idioms rule now covers developer
figurative verbs (spin up, tear down, stand up).
- **README**: registers the new page and adds ASD-STE100 to the
third-party references.

All new rules are documentation-only (no Vale rule) because they need
editorial judgment rather than pattern matching.

---

🤖 Built with AI assistance.
This commit is contained in:
Nick Vigilante
2026-08-06 10:17:41 -04:00
committed by GitHub
parent aa039479ed
commit 2d320de71e
5 changed files with 288 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.style/style-guide/README.md
+18 -16
View File
@@ -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
@@ -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) |
docs/.style/style-guide/accessibility-and-inclusion.md
+5 -1
View File
@@ -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`.*
@@ -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).
docs/.style/style-guide/procedural-writing.md
+160
View File
@@ -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)
docs/.style/style-guide/voice-and-tone.md
+79
View File
@@ -119,6 +119,81 @@ Use plain present tense for behavior the product already exhibits.
*Documentation-only.
No Vale rule.*
## Keep sentences and paragraphs short
Aim for 25 words or fewer per sentence in body prose.
Step sentences in a procedure get a tighter budget: refer to [Keep steps short](./procedural-writing.md#keep-steps-short).
Give each paragraph one topic and open with the sentence that states it.
Split a paragraph when it grows past roughly 6 sentences.
The budgets are targets, not ceilings.
A sentence that needs 30 words to be precise beats two vague short ones.
**Do**:
> The provisioner reads the template files and validates them against the schema.
> It then creates the workspace and starts the agent.
**Don't**:
> The provisioner, which reads the template files that the administrator pushed and validates them against the schema before it creates any resources, then creates the workspace and starts the agent.
*Adapted from ASD-STE100 Issue 9, rules 6.1 to 6.6.
Documentation-only.
No Vale rule.*
## Prefer verbs over noun forms
English can wrap an action in a noun ("perform the installation of") instead of stating the verb ("install").
The noun form adds words and hides the actor.
Use the verb.
**Do**:
> Before you remove the template, export its insights.
>
> Coder validates the token on each request.
**Don't**:
> Before the removal of the template, perform an export of its insights.
>
> Coder performs validation of the token on each request.
*Adapted from ASD-STE100 Issue 9, rule 3.7.
Documentation-only.
No Vale rule.*
## Give each pronoun one clear referent
A pronoun (`it`, `this`, `they`, `that`) must point to exactly one thing.
If the pronoun can point to two nouns, repeat the noun instead.
The repetition reads slightly worse to the writer and much clearer to the reader.
The same rule covers a bare `this` that summarizes a whole clause.
Name the thing that `this` refers to.
**Do**:
> Restart the server and the agent.
> The agent reconnects automatically.
>
> The build can fail when the quota is exhausted.
> This failure appears in the audit log.
**Don't**:
> Restart the server and the agent.
> It reconnects automatically.
>
> The build can fail when the quota is exhausted.
> This appears in the audit log.
*Adapted from ASD-STE100 Issue 9, general recommendations GR-3 and GR-4.
Documentation-only.
No Vale rule.*
## Contractions are the default
Contractions match how a reader's internal voice sounds.
@@ -183,6 +258,10 @@ The contracted forms read fast and let a busy reader skip past the warning.
>
> You can't undo `coder delete`.
**The default trades against the international audience.** Plain-language guidance for non-native readers, including [ASD-STE100](https://www.asd-ste100.org/), bans contractions because the expanded forms are easier to parse and to machine-translate.
The Coder docs keep contractions because the genre reads conversationally and the [reading-level target](./accessibility-and-inclusion.md#reading-level) already bounds sentence complexity.
The high-stakes exception above applies the STE logic exactly where a misreading costs the most.
*Documentation-only.
No Vale rule.*
docs/.style/style-guide/word-choice.md
+26
View File
@@ -109,6 +109,32 @@ It isn't itself the concept, so it stays in backticks as a tool name.
*Enforced by `Coder.DevContainer` (planned).*
## One term per concept
Pick one name for each thing, then use that name every time the thing appears.
Synonyms read as new concepts.
A page that alternates between "workspace", "environment", and "dev box" makes the reader ask whether the three differ.
The [glossary](../../reference/glossary.md) is the registry of canonical names.
When a concept has a glossary entry, use the entry's term.
The same rule covers repeated instructions inside one page.
Word the same action the same way each time it occurs, so the reader recognizes it as the same action.
**Do**:
> Create the workspace from the template.
> When the workspace starts, the agent runs the startup script.
**Don't**:
> Create the workspace from the template.
> When the environment starts, the agent runs the init script.
*Adapted from ASD-STE100 Issue 9, rules 1.11 and 9.4.
Documentation-only.
No Vale rule.*
## Phrasal verbs and their noun forms
English uses two spellings for many product actions: two words when the term is a verb (`set up`, `log in`), and one word (or hyphenated) when the term is a noun (`setup`, `login`).