diff --git a/docs/.style/style-guide/README.md b/docs/.style/style-guide/README.md index 21b934106bfa5..53cc88908890c 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 761a0ad23c125..4265e097c01b7 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. @@ -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/formatting.md b/docs/.style/style-guide/formatting.md index 9d2ce3df79c0f..e77d89289c691 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. diff --git a/docs/.style/style-guide/procedural-writing.md b/docs/.style/style-guide/procedural-writing.md new file mode 100644 index 0000000000000..110ceec9c8fb0 --- /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 a19b25cf6d57d..e2ec9300daf15 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 6e2b03f02e57d..ff7aeb096ae44 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`).