From 2d320de71e72f40f9d0a0622f6c18fa662a06a61 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Thu, 6 Aug 2026 10:17:41 -0400 Subject: [PATCH] docs(docs/.style/style-guide): adopt STE-derived prose rules (#27852) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/.style/style-guide/README.md | 34 ++-- .../accessibility-and-inclusion.md | 6 +- docs/.style/style-guide/procedural-writing.md | 160 ++++++++++++++++++ docs/.style/style-guide/voice-and-tone.md | 79 +++++++++ docs/.style/style-guide/word-choice.md | 26 +++ 5 files changed, 288 insertions(+), 17 deletions(-) create mode 100644 docs/.style/style-guide/procedural-writing.md diff --git a/docs/.style/style-guide/README.md b/docs/.style/style-guide/README.md index 21b934106b..53cc889088 100644 --- a/docs/.style/style-guide/README.md +++ b/docs/.style/style-guide/README.md @@ -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) | diff --git a/docs/.style/style-guide/accessibility-and-inclusion.md b/docs/.style/style-guide/accessibility-and-inclusion.md index 8074b769a7..4265e097c0 100644 --- a/docs/.style/style-guide/accessibility-and-inclusion.md +++ b/docs/.style/style-guide/accessibility-and-inclusion.md @@ -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). diff --git a/docs/.style/style-guide/procedural-writing.md b/docs/.style/style-guide/procedural-writing.md new file mode 100644 index 0000000000..110ceec9c8 --- /dev/null +++ b/docs/.style/style-guide/procedural-writing.md @@ -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) diff --git a/docs/.style/style-guide/voice-and-tone.md b/docs/.style/style-guide/voice-and-tone.md index a19b25cf6d..e2ec9300da 100644 --- a/docs/.style/style-guide/voice-and-tone.md +++ b/docs/.style/style-guide/voice-and-tone.md @@ -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.* diff --git a/docs/.style/style-guide/word-choice.md b/docs/.style/style-guide/word-choice.md index 9a255294f7..45cb48d117 100644 --- a/docs/.style/style-guide/word-choice.md +++ b/docs/.style/style-guide/word-choice.md @@ -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`).