From 6c56017b222e66b6fe9367c04eafb4fc3ee21624 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Tue, 4 Aug 2026 12:14:26 -0400 Subject: [PATCH] docs(docs/.style/style-guide): fix self-violations found by audit Run every style guide page through the guide's own rules, including the STE-derived rules added in the previous commit, and fix the violations in the guide's prose and Do examples. Don't examples keep their intentional violations. Highlights: - Objective defects: an unbalanced quotation mark, a stale "this PR" reference, a mangled console Do example, inline "[!NOTE]" markers that GitHub renders as literal text, "a onClick", and stale Vale rule references (write-good.Reading, Google.Ordinal). - A Do example on the audience page used the exact metadata line the same page bans; a Do example on the word-choice page had Coder running its own login command. - US-style quotation: commas and periods moved inside closing quotes throughout the guide's own prose. - Banned vocabulary in guide prose: navigational directionality ("above"), idioms ("wall of", "silently rots", "when in doubt", "stretch goal", "bleeding-edge", "put up with"), simplicity words ("easy", "straightforward", "clearly"), and vague qualifiers ("typically", "almost always", "often", "rarely"). - Structure: framing paragraphs under bare headings, one sentence per source line for run-in bold leads and split example sentences, prose semicolons split into sentences, 6-item prose enumerations reduced or split, and long sentences brought under the budget. - Heading consistency: end-of-page "Related" sections renamed to "Learn more" to match the guide's own heading rule. - Policy clarification, flagged for docs-team review: the digits-everywhere rule now scopes out numbers that describe language itself and "one" as a determiner or pronoun, and the remaining prose converts real counts to digits. Assisted-by: AI --- docs/.style/style-guide/README.md | 17 +++-- .../accessibility-and-inclusion.md | 63 +++++++++------- docs/.style/style-guide/audience-and-scope.md | 49 +++++++------ .../capitalization-and-punctuation.md | 12 +-- docs/.style/style-guide/editor-setup.md | 7 +- docs/.style/style-guide/formatting.md | 73 +++++++++++-------- .../style-guide/numbers-units-and-dates.md | 23 ++++-- docs/.style/style-guide/procedural-writing.md | 11 +-- docs/.style/style-guide/voice-and-tone.md | 28 ++++--- docs/.style/style-guide/word-choice.md | 34 +++++---- 10 files changed, 179 insertions(+), 138 deletions(-) diff --git a/docs/.style/style-guide/README.md b/docs/.style/style-guide/README.md index 53cc88908890c..f62817b411aff 100644 --- a/docs/.style/style-guide/README.md +++ b/docs/.style/style-guide/README.md @@ -7,7 +7,7 @@ For decisions about what belongs in the docs and what doesn't, refer to [`conten Each rule on the linked pages is a policy decision the Coder docs team has made. Where a Vale rule already enforces the policy, the rule name is listed in a parenthetical so you can reproduce the warning locally. Where the rule is documentation-only, the parenthetical says so. -The doctrine for adding Vale rules lives in [`README.md`](../README.md). +The doctrine for adding Vale rules lives in the [Vale doctrine README](../README.md). ## How to use this guide @@ -44,22 +44,23 @@ Each sentence sits on its own Markdown source line. Sentences aren't split across lines, and lines don't wrap to a fixed column width. The rendered Markdown joins lines inside a paragraph back together, so the source line breaks don't appear in the rendered output. -Reviewers reading the diff do encounter them, and they make diffs land cleanly at the sentence level. +Reviewers reading the diff do encounter them, and the per-sentence lines make diffs land cleanly at the sentence level. `markdownlint`'s `MD013` (line length) is already disabled, so the convention is editorial. -Editors that auto-wrap on save should be configured to leave the source alone. +Configure editors that auto-wrap on save to leave the source alone. #### Incremental adoption The Coder docs corpus predates this convention. -Much of the existing prose still wraps to a fixed column width or runs on a single long line, and some paragraphs on the other pages of this style guide still carry semantic line breaks (sembr) from earlier commits in this PR. +Much of the existing prose still wraps to a fixed column width or runs on a single long line. +Some paragraphs on the other pages of this style guide still carry semantic line breaks (sembr) from earlier commits. The convention is adopted incrementally. -When a contributor edits any line inside a paragraph, the entire paragraph is reformatted to one sentence per line as part of the same edit. +A contributor who edits any line inside a paragraph reformats the entire paragraph to one sentence per line as part of the same edit. The contributor doesn't reformat surrounding paragraphs they didn't otherwise touch. For this rule, a bullet item, a numbered list entry, and a blockquote line are each their own paragraph. -Headings, fenced code blocks, and tables are out of scope: headings are single lines by convention, code blocks render their source verbatim, and table rows are governed by `markdown-table-formatter`. +Headings, fenced code blocks, and tables are out of scope: headings are single lines by convention, code blocks render their source verbatim, and `markdown-table-formatter` governs table rows. ### The style guide doesn't use "see" for navigation @@ -78,7 +79,7 @@ Each enabled rule lands via a dedicated PR that: 2. Adds the rule line in `.vale.ini` at the rule author's chosen severity. 3. Adds the corresponding section to the appropriate subpage of this guide. -Severity is a deliberate per-rule choice from the three-tier ladder: +Severity is a deliberate per-rule choice among 3 tiers: - `error` blocks merge in CI. Use for hard policy where any violation is wrong. @@ -87,7 +88,7 @@ Severity is a deliberate per-rule choice from the three-tier ladder: - `suggestion` surfaces a `notice` annotation. Use for soft guidance where the right fix is contextual. -The full doctrine, including the false-positive policy, lives in [`README.md`](../README.md). +The full doctrine, including the false-positive policy, lives in the [Vale doctrine README](../README.md). This guide is itself exempt from the Coder rules: it demonstrates the violations those rules ban, so the repo-root `.vale.ini` clears `BasedOnStyles` for `docs/.style/style-guide/**`. Zero baseline is measured over `docs/` excluding `docs/.style/style-guide/`. Run `make lint/prose` to reproduce the baseline locally. diff --git a/docs/.style/style-guide/accessibility-and-inclusion.md b/docs/.style/style-guide/accessibility-and-inclusion.md index 4265e097c01b7..f096cb49e02ab 100644 --- a/docs/.style/style-guide/accessibility-and-inclusion.md +++ b/docs/.style/style-guide/accessibility-and-inclusion.md @@ -1,10 +1,12 @@ # Accessibility and inclusion -The Coder documentation aims for [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level AA conformance as a minimum, with Level AAA as a stretch goal where it doesn't sacrifice clarity. +The Coder documentation aims for [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level AA conformance as a minimum, with Level AAA conformance wherever it doesn't sacrifice clarity. The rules on this page support that target. -They cover heading structure, inclusive language, link text, images, plain English for international readers, page descriptions, and reading level. +They cover heading structure, inclusive language, link text, and images. +They also cover plain English for international readers, page descriptions, and reading level. -> [!NOTE] Color contrast and other rendered-output a11y concerns belong to the docs site theme, not to prose conventions. +> [!NOTE] +> Color contrast and other rendered-output accessibility concerns belong to the docs site theme, not to prose conventions. > The Coder docs team tracks color-contrast conformance separately. ## Heading structure and placement @@ -33,12 +35,11 @@ The following sections cover SSH access and environment variables. ## Set up SSH access SSH access uses the agent that runs inside your workspace. -Two client setups are documented in the following sections. +The following sections cover 2 client setups. ### Connect through JetBrains Toolbox -Install the Coder plugin in JetBrains Toolbox, -then connect to your workspace by name. +Install the Coder plugin in JetBrains Toolbox, then connect to your workspace by name. ### Connect through VS Code Remote SSH @@ -59,8 +60,7 @@ Define them in the template or in the workspace's parameters. #### Connect through JetBrains Toolbox -Install the Coder plugin in JetBrains Toolbox, -then connect to your workspace by name. +Install the Coder plugin in JetBrains Toolbox, then connect to your workspace by name. ``` The second H1 creates two competing page titles. @@ -126,8 +126,8 @@ The alt text describes what the image shows or what purpose it serves. It isn't a caption. Captions follow the image in a `` tag. -Aim for one or two sentences that convey the same information a sighted reader would extract from the image. -Lead with the subject, not "An image of" or "A screenshot showing". +Aim for 1 or 2 sentences that convey the same information a sighted reader would extract from the image. +Lead with the subject, not "An image of" or "A screenshot showing." ```md ![Template Insights dashboard with weekly active users and connection latency charts](../../images/admin/templates/template-insights.png) @@ -135,7 +135,7 @@ Lead with the subject, not "An image of" or "A screenshot showing". The Template Insights dashboard with active-user and connection-latency widgets. ``` -For complex diagrams that can't be summarized in alt text, provide a longer description in the body of the page and reference it from the alt text. +For diagrams that alt text can't summarize, provide a longer description in the body of the page and reference it from the alt text. *Enforced by `markdownlint` rule `MD045` for the alt-text-required requirement.* @@ -150,7 +150,7 @@ Empty alt text tells the screen reader to skip the image rather than announce a Decorative images are rare in the Coder docs. Most images shown to a reader are screenshots or diagrams that convey information, and those images need descriptive alt text. -When in doubt, write descriptive alt text. +If you aren't sure, write descriptive alt text. *Documentation-only. No Vale rule.* @@ -158,7 +158,7 @@ No Vale rule.* ## Directional language Screen-reader users navigate documents linearly and don't experience the visual layout. -Phrases like "see below", "above the table", or "the menu on the left" lose meaning when the reader can't see where elements sit on the page. +Phrases like "see below," "above the table," or "the menu on the left" lose meaning when the reader can't see where elements sit on the page. Sighted readers also benefit from semantic references when the page gets restructured or they jump in through an anchor link. Refer to content by section heading, by document order (`the previous section`, `the following section`), or by anchor link. @@ -193,7 +193,7 @@ Common replacements: | 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. +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. *Documentation-only. No Vale rule.* @@ -206,7 +206,7 @@ Two patterns add friction for non-native speakers without adding meaning, so the ### Avoid idioms and figurative language Idioms (`under the weather`, `ballpark figure`, `get the ball rolling`, `at the eleventh hour`) and figurative language (`unleash`, `supercharge`, `dive in`, `out of the box`) rely on cultural context that doesn't translate. -They also rarely add precision. +They add no precision. Replace them with the literal meaning. **Do**: @@ -226,7 +226,7 @@ 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". +"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. @@ -235,7 +235,8 @@ Planned Vale rule `Coder.Idioms`.* ### Latin abbreviations The following Latin abbreviations are fine in Coder docs. -Use them when they fit the sentence; the English equivalent is also fine. +Use them when they fit the sentence. +The English equivalent is also fine. | Abbreviation | Meaning | Notes | |--------------|------------------------------------------------|----------------------------------------------------------------------------| @@ -245,7 +246,8 @@ Use them when they fit the sentence; the English equivalent is also fine. | `vs.` | versus, against, as opposed to, in contrast to | No comma. Example: `coder server vs. coder agent`. | | `et al.` | and others | Citation contexts only. Follow the citation style's punctuation rules. | -**Prefer parentheses around `e.g.` and `i.e.` clauses.** The parentheses make the sentence structure obvious and avoid a cascade of commas around the abbreviation. +**Prefer parentheses around `e.g.` and `i.e.` clauses.** +The parentheses make the sentence structure obvious and avoid a cascade of commas around the abbreviation. **Do**: @@ -261,7 +263,8 @@ Use them when they fit the sentence; the English equivalent is also fine. The **Don't** versions are grammatical, but the comma cascade makes the sentence structure harder to follow. -**One period when `etc.` ends a sentence.** The period in `etc.` doubles as the sentence-ending period. +**One period when `etc.` ends a sentence.** +The period in `etc.` doubles as the sentence-ending period. **Do**: @@ -280,7 +283,8 @@ The abbreviation's period closes `etc.`, the closing parenthesis follows, and th The same rule applies if `e.g.` or `i.e.` ever sits at the end of a sentence, though that placement is unusual. -**Citation form for `et al.`** In an author-date citation, place a comma between the author phrase and the year, and keep the abbreviation's period. +**Citation form for `et al.`** +In an author-date citation, place a comma between the author phrase and the year, and keep the abbreviation's period. **Do**: @@ -288,7 +292,8 @@ The same rule applies if `e.g.` or `i.e.` ever sits at the end of a sentence, th > > The protocol is described by Smith et al. (2020). -**Less common Latin abbreviations aren't allowed.** Latin abbreviations beyond the five in the table, such as `a priori`, `q.v.`, `viz.`, `n.b.`, `cf.`, and `ibid.`, are unfamiliar to many readers and easy to misuse. +**Less common Latin abbreviations aren't allowed.** +Latin abbreviations beyond the five in the table, such as `a priori`, `q.v.`, `viz.`, `n.b.`, `cf.`, and `ibid.`, are unfamiliar to non-specialist readers and invite misuse. Replace them with plain English. **Don't**: @@ -303,7 +308,9 @@ Replace them with plain English. Major plain-language guides such as the [Google developer documentation style guide](https://developers.google.com/style/abbreviations), the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/abbreviations/), the [18F Content Guide](https://content-guide.18f.gov/our-style/inclusive-language/), and the [Plain Language Action and Information Network (PLAIN) federal guidance](https://www.plainlanguage.gov/guidelines/words/use-simple-words-phrases/) recommend English equivalents for all Latin abbreviations. The argument is that the abbreviations are unfamiliar to many readers and frequently misused (`i.e.` confused with `e.g.`). -The Coder docs follow the spirit of that guidance for less common Latin but make an exception for `e.g.`, `i.e.`, `etc.`, `vs.`, and `et al.` These five are near-universal in industry technical writing; restricting them adds friction for writers without a clear payoff for readers familiar with the conventions of the genre. +The Coder docs follow the spirit of that guidance for less common Latin but make an exception for `e.g.`, `i.e.`, `etc.`, `vs.`, and `et al.` +These five are near-universal in industry technical writing. +Restricting them burdens writers without a matching gain for readers familiar with the conventions of the genre. @@ -322,15 +329,15 @@ A page's H1 and its sidebar title serve different jobs and may diverge. The Coder docs site reads the sidebar title from the `title` field in [`docs/manifest.json`](../../manifest.json). The two must each stand alone, but they don't need to be identical. -Breadcrumb depth gives one layer of context for free. +Breadcrumb depth already supplies one layer of context. The sidebar title can drop redundancy that the parent breadcrumbs already imply. Worked example. -A page reachable through **Administration** > **Authentication** > **Google** has parent breadcrumbs that already say "Administration" and "Authentication". +A page reachable through **Administration** > **Authentication** > **Google** has parent breadcrumbs that already say "Administration" and "Authentication." The sidebar title can be `Google` alone, and the H1 can be `Configure Google authentication with Coder`. Both labels stand alone in their own context. -When the H1 and the sidebar title coincide (often the case for short-titled pages), that's fine. +When the H1 and the sidebar title coincide (common for short-titled pages), that's fine. When they diverge, the divergence is intentional and serves the reader. The same pattern is common in mature docs sites. AWS, Microsoft Learn, and GitHub Docs all pair task-focused H1s with shorter noun-focused sidebar titles. @@ -424,7 +431,7 @@ A reading-level rule is part of [WCAG 2.1 Level AAA](https://www.w3.org/TR/WCAG2 The criterion is satisfied either by writing at the lower-secondary reading level or by providing an alternative version. Coder docs write at the target reading level directly. -Editors that surface a grade-level score (Hemingway, Vale's `write-good.Reading`) are a useful spot check. +Editors that surface a grade-level score (Hemingway, Vale's `Readability.FleschKincaid`) are a useful spot check. The grade level isn't a hard ceiling. A reference page that requires technical vocabulary will read higher than a tutorial, and that's correct. @@ -435,12 +442,12 @@ No Vale rule wired.* The docs site theme controls color contrast, not the prose written on each page. Tracked separately from this guide. -The target is WCAG 2.1 Level AA for normal text (contrast ratio 4.5:1) and Level AA for large text (3:1), with AAA (7:1 normal, 4.5:1 large) as the stretch goal. +The target is WCAG 2.1 Level AA for normal text (contrast ratio 4.5:1) and Level AA for large text (3:1), with AAA (7:1 normal, 4.5:1 large) as the further target. *Out of scope for this guide. Tracked by the docs site theme.* -## Related +## Learn more - [Style guide landing page](./README.md) - [Voice and tone](./voice-and-tone.md) diff --git a/docs/.style/style-guide/audience-and-scope.md b/docs/.style/style-guide/audience-and-scope.md index 5b1828d81ee63..2b789ad954c87 100644 --- a/docs/.style/style-guide/audience-and-scope.md +++ b/docs/.style/style-guide/audience-and-scope.md @@ -5,13 +5,14 @@ The audience determines vocabulary, depth, and the prior knowledge the page assu The outcome determines what the page covers and where it stops. Pages that try to serve two audiences, or chain multiple unrelated outcomes, serve none of their readers well. -A reader who is one persona away from the page's target has to skip past content that doesn't apply to them, guess which sentences are for them, and trust the writer not to have buried a step they need inside a section labeled for someone else. +A reader who is one persona away from the page's target has to skip past content that doesn't apply to them. +They must guess which sentences are for them, and trust the writer not to have hidden a step they need inside a section labeled for someone else. The single canonical Coder example is **install Coder**. An end user wants to connect their local editor to a Coder workspace and start coding. A platform engineer wants to deploy the Coder control plane to their company's Kubernetes cluster. -Both groups search for "install Coder. -A page that tries to cover both forces the end user to read past Helm chart values, and forces the platform engineer to read past Visual Studio Code download links. +Both groups search for "install Coder." +A page that tries to cover both forces the end user to read past Helm chart values and forces the platform engineer to read past Visual Studio Code download links. Two pages, one per audience and one per outcome, serve both groups better than one page that combines them. ## Pick one audience per page @@ -32,9 +33,8 @@ Section tags don't save readers from scanning content that doesn't apply to them ```md # Connect Visual Studio Code to your Coder workspace -*Audience: a developer with an existing Coder workspace.* - -This page covers the Visual Studio Code IDE. +This page is for a developer with an existing Coder workspace. +It covers the Visual Studio Code IDE. For Cursor, refer to [Cursor](./cursor.md). For Windsurf, refer to [Windsurf](./windsurf.md). ``` @@ -90,7 +90,7 @@ A hub page may have a broad title and a short body when its job is to direct the Hub pages aren't an exemption from the audience and outcome rules. The audience is the reader looking for the right child page. -The outcome is making the routing decision in three or four lines. +The outcome is making the routing decision in 3 or 4 lines. A hub page is appropriate when: @@ -128,8 +128,8 @@ This page covers OIDC, SAML, GitHub OAuth, password authentication, and the API [300 lines of provider-specific configuration] ``` -The Don't example forces every reader to scan a wall of content for the section that applies to them. -The Do example routes them to the right page in four lines. +The Don't example forces every reader to scan the whole page for the section that applies to them. +The Do example routes them to the right page in 4 lines. A hub page doesn't need every link to be a direct child page in the file tree. Cross-references to sibling sections of the docs are valid when that's where the reader's next step lives. @@ -137,7 +137,7 @@ Cross-references to sibling sections of the docs are valid when that's where the ## Declare audience and scope up front The first paragraph of the page names the audience and the outcome. -The reader should know within the first two or three sentences whether the page is for them and whether it covers their task. +The reader should know within the first 2 or 3 sentences whether the page is for them and whether it covers their task. Conventions: @@ -188,13 +188,11 @@ For pages of that kind, add an `IMPORTANT` callout at the beginning of the page ```md # Configure single sign-on with Okta -This guide is for a Coder deployment administrator -who has access to both the Coder control plane and the Okta tenant. +This guide is for a Coder deployment administrator who has access to both the Coder control plane and the Okta tenant. > [!IMPORTANT] > You must be a Coder deployment administrator to complete this guide. -> If you aren't a deployment administrator, -> ask your administrator to complete the steps for you. +> If you aren't a deployment administrator, ask your administrator to complete the steps for you. ``` The prerequisite callout uses the role the reader recognizes (`Coder deployment administrator`), not the writer-facing persona name (`Perry the Platform Engineer`). @@ -206,7 +204,7 @@ A page written for a known audience gives that reader what they need to reach th Knowing the audience means knowing what that audience can already do. When the page assumes a reader who runs their own Coder deployment, that reader is their own administrator. -Don't hedge a step with "ask your administrator" or "if you have permission". +Don't hedge a step with "ask your administrator" or "if you have permission." Those caveats are written for a reader this page doesn't target, and they make the real reader doubt whether the step is meant for them. Before you add a caveat, a permission note, or an "if you don't have access" aside, check it against the audience and the full context of the page: @@ -215,9 +213,9 @@ Before you add a caveat, a permission note, or an "if you don't have access" asi - Has the page already established that this reader has the access? - Does the caveat help this reader, or only a reader who belongs on a different page? -If the caveat serves a different audience, cut it, or move it to the page that audience reads. +If the caveat serves a different audience, cut it or move it to the page that audience reads. -**Do** (a local-first Quickstart, where the reader started the server two pages earlier): +**Do** (a local-first Quickstart, where the reader started the server 2 pages earlier): > Configure a GitHub provider on your deployment, then create the workspace again. @@ -246,11 +244,13 @@ Inside a page, name the audience by the role the reader recognizes from their ow ### Primary personas +These personas cover the audiences most Coder docs pages serve. + #### Perry the Platform Engineer Perry builds self-service platforms for development teams at a mid-to-large enterprise. They own the templates, governance, and integrations that turn the Coder control plane Ada deploys into the default workflow developers actually use. -They need template authoring docs, RBAC and organization design, integration patterns, prebuilds, cost reporting, and policy-as-code. +They need template authoring docs (including prebuilds), RBAC and organization design, integration patterns, cost reporting, and policy-as-code. *Coder surface:* template authoring (Terraform, modules, prebuilds), RBAC, organizations and groups, policy and governance, integrations (CI/CD, observability, secrets, Git), audit logs. @@ -271,14 +271,15 @@ They don't need template authoring or infrastructure context. *Coder surface:* workspaces, web terminal, IDE and notebook integrations (VS Code, Jupyter, RStudio), dotfiles, port forwarding, SSH, file uploads and downloads. -> [!NOTE] Elliot is a stopgap umbrella persona for non-developer end users. +> [!NOTE] +> Elliot is a provisional persona that groups non-developer end users. > The Coder docs team plans to revisit the persona model with product and design once the broader audience is mapped out. #### Ada the Infrastructure Admin Ada runs the underlying infrastructure that Coder deploys onto: Kubernetes clusters, cloud accounts, networking, storage, identity, and security policy. -They need deployment, operation, and recovery docs: install paths, upgrade and rollback, IAM and SSO, monitoring and alerting, capacity planning, and incident playbooks. -Their success metric is uptime, so they trust proven, well-documented configurations over bleeding-edge defaults. +They need deployment, operation, and recovery docs: install paths, upgrade and rollback, IAM and SSO, monitoring and alerting, and operational playbooks for capacity and incidents. +Their success metric is uptime, so they trust proven, well-documented configurations over unproven defaults. *Coder surface:* control plane install (Helm, Docker, VM, airgapped), database, networking and DERP, IAM and SSO/OIDC/SAML, telemetry and audit logs, backup and disaster recovery. @@ -292,6 +293,8 @@ They need overview pages that explain what Coder is, how it fits the existing st ### Secondary personas +These personas appear in narrower feature areas. + #### Melissa the Machine Learner Melissa is an ML engineer who lives between Jupyter notebooks, Python, ML frameworks, and large datasets. @@ -327,7 +330,7 @@ They value precise, traceable numbers over feature descriptions. #### Sergio the Security Officer Sergio is the IT security officer at an organization with strict compliance requirements. -They need docs for the security architecture, identity and access control, secrets management, audit and compliance evidence (SOC 2, FedRAMP-style controls), data residency, and the supply chain story. +They need docs for the security architecture, identity and access control, secrets management, audit and compliance evidence (SOC 2, FedRAMP-style controls), and data residency and supply-chain posture. They are skeptical of new tools by default and want documented, auditable behavior. *Coder surface:* SSO and OIDC/SAML, RBAC, secrets management, audit logs, security architecture pages, compliance and trust-center content, allowlists and network policies. @@ -344,7 +347,7 @@ They run their team inside the guardrails Perry or Ada set up. *Documentation-only. No Vale rule.* -## Related +## Learn more - [Voice and tone](./voice-and-tone.md) - [Word choice](./word-choice.md) diff --git a/docs/.style/style-guide/capitalization-and-punctuation.md b/docs/.style/style-guide/capitalization-and-punctuation.md index 4fa5101a1dfc7..f272fee063baf 100644 --- a/docs/.style/style-guide/capitalization-and-punctuation.md +++ b/docs/.style/style-guide/capitalization-and-punctuation.md @@ -108,8 +108,8 @@ Both ignore characters inside backticks.* ## No em-dashes or en-dashes Em-dashes (—, U+2014), en-dashes (–, U+2013), and the ASCII `--` fallback are banned in prose. -Em-dashes typically set off a parenthetical aside or a break in thought. -Replace them with commas (for a tight aside), parentheses (for a clearly secondary aside), or a period and a new sentence (for a thought that stands on its own). +Em-dashes set off a parenthetical aside or a break in thought. +Replace them with commas (for a tight aside), parentheses (for a distinctly secondary aside), or a period and a new sentence (for a thought that stands on its own). **Do**: @@ -130,6 +130,8 @@ Replace them with commas (for a tight aside), parentheses (for a clearly seconda ## Commas +The following rules cover the comma cases that recur in the Coder docs. + ### Comma after an introductory element Place a comma after an introductory word, phrase, or clause that comes before the main clause. @@ -194,7 +196,7 @@ Use a comma before the conjunction in a list of three or more items. Place commas and periods inside closing quotation marks. Semicolons and colons stay outside. -This is the United States convention and matches the dominant style of the surrounding tech-docs ecosystem. +This placement is the United States convention and matches the dominant style of the surrounding tech-docs ecosystem. **Do**: @@ -209,7 +211,7 @@ This is the United States convention and matches the dominant style of the surro ## Semicolons sparingly Prefer two sentences. -A semicolon joins two complete thoughts when they're tightly related and a period would lose the connection, but in technical prose two sentences almost always read more clearly. +A semicolon joins two complete thoughts when they're tightly related and a period would lose the connection, but in technical prose two sentences read more clearly. **Do**: @@ -254,7 +256,7 @@ In code blocks, terse reference material, and tables where space matters, the hy *Enforced by `Google.Ranges`.* -## Related +## Learn more - [Style guide landing page](./README.md) - [Accessibility and inclusion](./accessibility-and-inclusion.md) diff --git a/docs/.style/style-guide/editor-setup.md b/docs/.style/style-guide/editor-setup.md index 959308e765b2d..7815ea076b965 100644 --- a/docs/.style/style-guide/editor-setup.md +++ b/docs/.style/style-guide/editor-setup.md @@ -1,11 +1,12 @@ # Editor setup -A future revision of this guide will cover Vale editor integration for VS Code, Cursor, JetBrains, and Neovim, so contributors get inline feedback before commit instead of CI failure after push. +A future revision of this guide will cover Vale editor integration for VS Code, Cursor, JetBrains, and Neovim. +The goal is inline feedback before commit instead of CI failure after push. This page is a placeholder. -The contents land in a follow-up PR. +A follow-up change adds the contents. -## Related +## Learn more - [Style guide landing page](./README.md) - [Vale doctrine and tooling](../README.md) diff --git a/docs/.style/style-guide/formatting.md b/docs/.style/style-guide/formatting.md index e77d89289c691..4b498b83ceb0a 100644 --- a/docs/.style/style-guide/formatting.md +++ b/docs/.style/style-guide/formatting.md @@ -2,7 +2,8 @@ Coder documentation uses bold for UI elements, italics for emphasis, and code font for identifiers. Code blocks declare a language. -The rules on this page set those defaults and the conventions for callouts, tabs, lists, tables, links, and images. +The rules on this page set those defaults. +The page also covers callouts and tabs, lists and tables, and links and images. For descriptive link text and image alt text, refer to [Accessibility and inclusion](./accessibility-and-inclusion.md). The accessibility-driven rules live on that page so heading structure, language, link text, and alt text stay together. @@ -12,9 +13,9 @@ The accessibility-driven rules live on that page so heading structure, language, Write each sentence on its own Markdown source line. Don't split a sentence across multiple lines, and don't wrap to a fixed column width. -The payoff is cleaner diffs and easier authoring. +The convention produces cleaner diffs and faster authoring. A sentence-level edit changes one line, not a paragraph reflow, so reviewers see exactly which sentence moved. -The rule is straightforward to apply for both humans and LLMs: end a sentence, start a new line. +The rule applies the same way for humans and LLMs: end a sentence, start a new line. What counts as a single line: @@ -50,10 +51,10 @@ 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. +Both **Don't** versions make the source harder to scan and cause spurious diffs on small edits. `markdownlint`'s `MD013` (line length) is already disabled, so the convention is editorial. -Editors that auto-wrap on save should be configured to leave the source alone. +Configure editors that auto-wrap on save to leave the source alone. *Documentation-only. No Vale rule.* @@ -65,7 +66,7 @@ The rules in this section cover inline formatting that lives inside a paragraph. ### Bold for UI elements Use bold for the literal text of UI elements the reader interacts with: buttons, menu items, page titles, field labels, tab names. -Bold tells the reader "this is the thing you select or read". +Bold tells the reader "this is the thing you select or read." When the reader navigates across multiple UI elements, join each element with a greater-than sign (`>`) surrounded by spaces. The separator makes the navigation path scannable and matches the convention in Microsoft and Google developer documentation. @@ -149,26 +150,33 @@ Use the most specific language tag available: Prefix each typed line with `$`. - `ps1` for Windows command-line blocks. PowerShell is the default Windows shell in the Coder docs. - `pwsh` and `powershell` are not the canonical tag; use `ps1`. - `ps1` is Shiki's PowerShell alias, and it's also GitHub's `.ps1` file extension, which its markdown renderer falls back to when a fence label isn't a recognized language name; `ps` isn't registered either way and won't highlight on GitHub today. + `pwsh` and `powershell` are not the canonical tag. Use `ps1`. + `ps1` is Shiki's PowerShell alias. + It's also GitHub's `.ps1` file extension, which GitHub's Markdown renderer falls back to when a fence label isn't a recognized language name. + `ps` isn't registered either way and won't highlight on GitHub today. - `tf` for Terraform and HCL. - `terraform` and `hcl` are not the canonical tag; use `tf`. - Shiki ships `terraform` and `hcl` as two distinct grammars; `tf` is an alias of the more specific `terraform` grammar (not `hcl`), and matches what nearly every Coder docs code block actually is. + `terraform` and `hcl` are not the canonical tag. Use `tf`. + Shiki ships `terraform` and `hcl` as two distinct grammars. + `tf` aliases the more specific `terraform` grammar (not `hcl`) and matches what nearly every Coder docs code block contains. - `yaml` for YAML. - `yml` is not the canonical tag; use `yaml`. + `yml` is not the canonical tag. Use `yaml`. - `go` for Go. - `json` for JSON. - `jsonc` is a distinct Shiki grammar for JSON that permits comments; use it only for blocks that actually contain comments, otherwise use `json`. + `jsonc` is a distinct Shiki grammar for JSON that permits comments. + Use it only for blocks that contain comments. + Otherwise use `json`. - `dotenv` for `.env`-style `KEY=VALUE` blocks. - `txt` for command output shown on its own, and for any block with no syntax to highlight. - `text`, `output`, `none`, and `url` are not the canonical tag; use `txt`. + `text`, `output`, `none`, and `url` are not the canonical tag. Use `txt`. - `dockerfile` for Dockerfiles, lowercase. `Dockerfile` (capitalized) is not a valid tag. - `md` for Markdown, including Markdown shown as a fenced example inside another Markdown file. - `markdown` is not the canonical tag; use `md`. + `markdown` is not the canonical tag. Use `md`. - `tsx` for TypeScript, including plain (non-JSX) TypeScript. - `ts` and `typescript` are not the canonical tag; use `tsx`. - `tsx` mis-tokenizes the legacy angle-bracket type-assertion syntax (`value`), which is invalid in real `.tsx` files anyway; write casts as `value as Type` instead, which is unambiguous under both grammars and is already the idiomatic style. + `ts` and `typescript` are not the canonical tag. Use `tsx`. + `tsx` mis-tokenizes the legacy angle-bracket type-assertion syntax (`value`), which is invalid in real `.tsx` files anyway. + Write casts as `value as Type` instead. + That form is unambiguous under both grammars and is already the idiomatic style. `bash` and `shell` are aliases of `sh`. Use `sh` so the corpus stays consistent. @@ -181,10 +189,11 @@ That output is generated. Do not copy the pattern into hand-written pages. The docs site highlights code with [Speed-Highlight](https://github.com/speed-highlight/core), which detects the language from the code content, not from the fence label. -The fence label still drives highlighting on GitHub and in most editors, and `markdownlint` rule `MD040` requires one, so always declare the most specific language. +The fence label still drives highlighting on GitHub and in code editors, and `markdownlint` rule `MD040` requires one, so always declare the most specific language. A future docs renderer may adopt [Shiki](https://shiki.style), which fails the build on a fence label it doesn't recognize as a language or alias, so use only tags Shiki supports. For content with no sensible language tag, fall back to `txt`. -A fence label needing a grammar Shiki doesn't bundle (for example `promql` or `caddyfile`) stays as-is; register it as a custom grammar when the site adopts Shiki, rather than degrading it to `txt`. +A fence label needing a grammar Shiki doesn't bundle (for example `promql` or `caddyfile`) stays as-is. +Register it as a custom grammar when the site adopts Shiki, rather than degrading it to `txt`. **Do**: @@ -194,7 +203,9 @@ coder templates push -d ~/coder-quickstart -y quickstart ``` ```console -$ coder templates list NAME LAST UPDATED quickstart 2 minutes ago +$ coder templates list +NAME LAST UPDATED +quickstart 2 minutes ago ``` ```` @@ -268,16 +279,16 @@ winget install Coder.Coder ```` -Leave a blank line after the opening `
` and before the closing `
` so the markdown processor parses the inner content as markdown rather than HTML. +Leave a blank line after the opening `
` and before the closing `
` so the Markdown processor parses the inner content as Markdown rather than HTML. *Documentation-only. No Vale rule.* ### Lists -If a sentence enumerates more than five items, rewrite as a bulleted list. -A prose list of six or more items reads as a wall of commas. -A bulleted list is easier to scan and to maintain. +If a sentence enumerates more than 5 items, rewrite it as a bulleted list. +A prose list of 6 or more items is hard to scan. +A bulleted list scans faster and takes less effort to maintain. Unordered lists are for items that have no required order. Ordered lists are for sequential steps the reader follows in order. @@ -335,7 +346,7 @@ The provisioner supports: The first **Don't** mixes punctuation styles and uses non-imperative leads. The second mixes punctuation inside one list and uses periods on single-word labels. -For a "Learn more" or "See also" list of links, treat each item as a label: no terminal period, and no leading "And" or "Or". +For a "Learn more" list of links, treat each item as a label: no terminal period, and no leading "And" or "Or." When such a list needs a lead-in, end the lead-in with a colon on a clause that stands on its own, rather than dangling the colon off a sentence the bullets then finish. **Do**: @@ -363,7 +374,7 @@ Install it where it persists across rebuilds: - Or bake it into the workspace image. ``` -The **Don't** dangles the colon off a sentence and starts a bullet with "Or". +The **Don't** dangles the colon off a sentence and starts a bullet with "Or." *Documentation-only. No Vale rule.* @@ -376,7 +387,7 @@ Avoid nested formatting and avoid tables that would read better as prose. Keep tables narrow enough that they fit the readable text column without horizontal scrolling. If a column needs more than a short phrase, rewrite the cell into the page body or break the table into two narrower tables. -A table that crushes column widths so words split across lines reads worse than the equivalent prose. +A table that forces columns so narrow that words split across lines reads worse than the equivalent prose. If a table needs many columns to capture the data, reconsider whether a table is the right structure. A definition list or a sequence of subsections may serve the reader better. @@ -425,15 +436,15 @@ Alt-text requirement enforced by `markdownlint` rule `MD045`.* ### Screenshots sparingly Use screenshots only when a sighted reader would be confused without the visual aid. -A worked example, a code block, or a precise written instruction is almost always better than a screenshot. +Prefer a worked example, a code block, or a precise written instruction over a screenshot. > If a picture is worth a thousand words, then a good example is worth at least twice that amount. > > Adapted from Lorna Jane Mitchell's [Short tech writing style guide for developers](https://lornajane.net/posts/2024/short-tech-writing-style-guide-for-developers). Screenshots carry an ongoing maintenance burden. -The product UI changes, strings get renamed, themes get retuned, and a screenshot that was accurate at merge time silently rots. -Readers who hit a stale screenshot lose confidence in the page, and a reader using a screen reader can't use the screenshot at all. +The product UI changes, strings get renamed, themes get retuned, and a screenshot that was accurate at merge time goes stale without warning. +Readers who encounter a stale screenshot lose confidence in the page, and a reader using a screen reader can't use the screenshot at all. The writer who adds a screenshot owns the cost of replacing it every time the captured surface changes. When a screenshot is the right answer: @@ -442,7 +453,7 @@ When a screenshot is the right answer: Crop to the smallest region that resolves the confusion the page is addressing. - Provide alt text that conveys the purpose of the screenshot, per [Alt text for images](./accessibility-and-inclusion.md#alt-text-for-images). - Pair the screenshot with the written instruction. - The written instruction is the source of truth. + The written instruction is authoritative. The screenshot is a check on the reader's understanding, not a replacement for the words. **Do**: @@ -461,7 +472,7 @@ The authoritative screenshot policy, including the obfuscation, PHI, and PII rul *Documentation-only. Enforcement is editorial.* -## Related +## Learn more - [Style guide landing page](./README.md) - [Accessibility and inclusion](./accessibility-and-inclusion.md) diff --git a/docs/.style/style-guide/numbers-units-and-dates.md b/docs/.style/style-guide/numbers-units-and-dates.md index 8828a79894308..08d9e4ee7a1a0 100644 --- a/docs/.style/style-guide/numbers-units-and-dates.md +++ b/docs/.style/style-guide/numbers-units-and-dates.md @@ -11,7 +11,15 @@ Digits are more accessible for the international and non-native-English audience If a sentence would start with a digit, restructure the sentence so a word comes first. Do not spell out the number to avoid the leading digit. -That reintroduces the rule the digits-everywhere policy is meant to remove. +Spelling out the number reintroduces the rule the digits-everywhere policy is meant to remove. + +The rule covers counts, quantities, measurements, and values: the numbers a reader scans for. +These uses stay spelled out: + +- Numbers that describe language itself, like word counts in a grammar discussion ("a contraction joins exactly two words") and numbers mentioned as words ("spell out first through ninth"). +- `One` when it works as `a single` or as a pronoun ("one topic per paragraph," "one of the two forms"). + +Rewriting those as digits changes the register of the sentence without making it easier to scan. **Do**: @@ -39,7 +47,7 @@ Restructure to put a word first ("The workspace has 5 connected users."). Insert a non-breaking space between a number and its unit so the pair never breaks across a line. The Markdown source uses ` ` (HTML entity) or the Unicode character `U+00A0` (the literal non-breaking space). -The visible result is the same as a regular space, but the line breaker treats the number and unit as one token. +The visible result is the same as a regular space, but the line breaker treats the number and unit as a single token. **Do**: @@ -56,8 +64,8 @@ In the rendered output (what the reader reads): > Connection latency under 150 ms shows green. The rendered output looks identical to text written with a regular space. -The difference shows up only at the end of a line: the browser will never split `30` and `seconds` across two lines. -To see the rule in action, shrink the browser window until the sentence wraps. +The difference shows up only at the end of a line: the browser never splits `30` and `seconds` across 2 lines. +To check the behavior, shrink the browser window until the sentence wraps. The number and the unit move to the next line together rather than separating. **Don't**: @@ -122,7 +130,7 @@ The 12-hour rule is for prose only. Spell out ordinals `first` through `ninth`. Use digits with a suffix for `10th` and higher. -This is the one place the digits-everywhere rule yields, because ordinals spelled out read more naturally in prose at low counts. +Ordinals are the one place the digits-everywhere rule makes an exception, because spelled-out ordinals read more naturally in prose at low counts. **Do**: @@ -136,9 +144,10 @@ This is the one place the digits-everywhere rule yields, because ordinals spelle > > The tenth workspace in the list is the oldest. -*Enforced by `Google.Ordinal` (planned).* +*Enforced by a planned scoped fork of `Google.Ordinal`. +The stock rule spells out all ordinals, so it cannot enforce this policy as written.* -## Related +## Learn more - [Style guide landing page](./README.md) - [Capitalization and punctuation](./capitalization-and-punctuation.md) diff --git a/docs/.style/style-guide/procedural-writing.md b/docs/.style/style-guide/procedural-writing.md index 110ceec9c8fb0..16850f6c84b06 100644 --- a/docs/.style/style-guide/procedural-writing.md +++ b/docs/.style/style-guide/procedural-writing.md @@ -8,7 +8,8 @@ For the callout syntax and severity table, refer to [Formatting](./formatting.md 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. +The Coder docs adopt its procedure-level discipline. +The controlled dictionary and the grammar restrictions stay out, because they serve that stricter audience. ## One instruction per step @@ -29,7 +30,7 @@ Two actions belong in one step only when they happen at the same time. 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. +The second example stays a single step because its actions overlap in time. **Don't**: @@ -37,7 +38,7 @@ The second example is one step because the two actions overlap in time. 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. +The actions happen in sequence, so they belong in separate steps. *Adapted from ASD-STE100 Issue 9, rule 5.2. Documentation-only. @@ -75,7 +76,7 @@ Steps get a tighter budget because the reader is mid-task and holds the instruct 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. +Don't cut words that carry meaning to meet the budget. **Do**: @@ -152,7 +153,7 @@ A warning that names no consequence reads as decoration, and the reader cannot w Documentation-only. No Vale rule.* -## Related +## Learn more - [Style guide landing page](./README.md) - [Voice and tone](./voice-and-tone.md) diff --git a/docs/.style/style-guide/voice-and-tone.md b/docs/.style/style-guide/voice-and-tone.md index e2ec9300daf15..f05e8ece05049 100644 --- a/docs/.style/style-guide/voice-and-tone.md +++ b/docs/.style/style-guide/voice-and-tone.md @@ -70,7 +70,7 @@ Do not use first-person plural for: The first **Don't** uses "we" to mean the product rather than the company. Rewrite with the product, release, or feature as the subject ("Each release includes ..."). The second **Don't** uses "we" to refer to the product's release behavior. -The third **Don't** uses "we" to mean "the docs and the reader together", which obscures who runs the command. +The third **Don't** uses "we" to mean "the docs and the reader together," which obscures who runs the command. *Enforced by `Coder.FirstPersonPlural`.* @@ -212,7 +212,8 @@ Expand a contraction only when one of the following exceptions applies. > > If you are using PostgreSQL, set the connection string before starting `coder server`. -**Auxiliary contractions need a complement.** `you'd`, `there's`, `it's`, `we'd`, and `they're` carry an unspoken verb form, participle, or adjective. +**Auxiliary contractions need a complement.** +`you'd`, `there's`, `it's`, `we'd`, and `they're` carry an unspoken verb form, participle, or adjective. They can't end a sentence because the elided word goes missing with them. Negation contractions like `don't`, `won't`, and `can't` end sentences fine because the elided `not` is itself the complement. @@ -228,7 +229,8 @@ Negation contractions like `don't`, `won't`, and `can't` end sentences fine beca > > The agent reattaches whenever there's. -**One contraction joins exactly two words.** Triple-word contractions like `you'd've`, `wouldn't've`, and `shouldn't've` cram three words into one apostrophe-laden form. +**One contraction joins exactly two words.** +Triple-word contractions like `you'd've`, `wouldn't've`, and `shouldn't've` compress three words into one apostrophe-laden form. Expand one of the two contractions, keeping whichever reads more naturally in context. **Do**: @@ -241,7 +243,8 @@ Expand one of the two contractions, keeping whichever reads more naturally in co > If you'd've finished the upgrade earlier, the migration wouldn't've failed. -**Spell out for emphasis and high-stakes operations.** Data loss, security warnings, and irreversible operations like deletions deserve the full visual weight of `do not`, `cannot`, and `will not`. +**Spell out for emphasis and high-stakes operations.** +Data loss, security warnings, and irreversible operations like deletions deserve the full visual weight of `do not`, `cannot`, and `will not`. The contracted forms read fast and let a busy reader skip past the warning. **Do**: @@ -258,9 +261,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 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 simpler 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. +The high-stakes exception earlier in this section applies the STE logic exactly where a misreading costs the most. *Documentation-only. No Vale rule.* @@ -269,10 +273,10 @@ No Vale rule.* A sentence that ends with a preposition (`with`, `to`, `from`, `for`, `on`, `of`, `at`, `by`, `into`, `over`, `under`, `about`) can leave its object implicit, which adds a small comprehension cost. Avoiding the trailing preposition, though, can produce a more awkward sentence. -There's no one-size-fits-all rule. +No single rule covers every case. Read both versions and keep the one that reads more naturally. -Lean toward rewriting when the trailing preposition is redundant, or when the reordered version is still easy to read: +Lean toward rewriting when the trailing preposition is redundant, or when the reordered version still reads naturally: **Do**: @@ -293,25 +297,25 @@ Keep the trailing preposition when avoiding it contorts the sentence: **Do**: -> This is some nonsense that I will not put up with. +> That's an error you can't recover from. > > Open the repository you want to clone from. **Don't**: -> This is some nonsense up with which I will not put. +> That's an error from which you can't recover. > > Open the repository from which you want to clone. The first **Don't** is the classic over-correction: the rewrite is harder to read than the preposition it avoids. When both versions read equally well, the writer chooses. -Treat avoiding a trailing preposition as a default to reach for, not a rule to enforce. +Treat avoiding a trailing preposition as a default to prefer, not a rule to enforce. *Documentation-only. No Vale rule.* -## Related +## Learn more - [Style guide landing page](./README.md) - [Word choice](./word-choice.md) diff --git a/docs/.style/style-guide/word-choice.md b/docs/.style/style-guide/word-choice.md index 45cb48d117d83..7b8a999fe1011 100644 --- a/docs/.style/style-guide/word-choice.md +++ b/docs/.style/style-guide/word-choice.md @@ -28,13 +28,13 @@ It reads as a misspelling of the product name. **Do**: -> Coder runs `coder login` to authenticate against the Coder server. +> Run `coder login` to authenticate against the Coder server. > > Open the AI Gateway integration page to configure model providers. **Don't**: -> coder runs coder login to authenticate against the coder server. +> Run coder login to authenticate against the coder server. > > Open the ai gateway integration page to configure model providers. @@ -80,7 +80,8 @@ The Coder docs follow the same conventions. `envbuilder` is the implementation tool Coder uses to build dev containers. It isn't itself the concept, so it stays in backticks as a tool name. -> [!NOTE] The Coder feature that integrates the open standard with Coder workspaces is named `Dev Containers` in product context. +> [!NOTE] +> The Coder feature that integrates the open standard with Coder workspaces is named `Dev Containers` in product context. > The capitalization there comes from the [Coder product and feature names](#coder-product-and-feature-names) rule for Coder features, not from the underlying concept. | Do | Don't | @@ -113,7 +114,7 @@ It isn't itself the concept, so it stays in backticks as a tool name. 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. +A page that alternates between "workspace," "environment," and "dev box" makes the reader ask whether the three terms differ. The [glossary](../../reference/glossary.md) is the registry of canonical names. When a concept has a glossary entry, use the entry's term. @@ -151,7 +152,7 @@ Treat them consistently across the docs. | start up | startup | | shut down | shutdown | -`Quickstart` is one word, always, even though it derives from "quick start". +`Quickstart` is one word, always, even though it derives from "quick start." **Do**: @@ -217,7 +218,7 @@ The plain-language alternatives carry register information that "see" doesn't, a The same reservation covers "see" used to mean "understand" or "find out". In a list of outcomes, "learn why the build fails" or "find out why the build fails" names what the reader gains. -"See why the build fails" borrows the observational sense of "see" for a comprehension outcome, so prefer "learn" or "find out". +"See why the build fails" borrows the observational sense of "see" for a comprehension outcome, so prefer "learn" or "find out." **Do**: @@ -244,7 +245,7 @@ In a list of outcomes, "learn why the build fails" or "find out why the build fa ## Learn more, not Next steps End-of-page navigation that points the reader at related material uses the heading **Learn more**, not **Next steps**. -Two rationales apply: +The heading choice rests on 2 rationales: - **Sequencing**: "Next steps" implies the reader must follow a specific sequence. "Learn more" frames the section as optional related reading, which matches the Diátaxis distinction between a tutorial (sequenced) and a how-to or reference (independent). @@ -270,10 +271,10 @@ Two rationales apply: - [Set workspace autostart](./autostart.md) ``` -### Sequenced tutorials: What's next? +### The What's next? section in sequenced tutorials A tutorial in an ordered series may add a **What's next?** section that points to the single next tutorial in that series. -Place it above **Learn more**, and write it as a short sentence with the link. +Place it before **Learn more** and write it as a short sentence with the link. **What's next?** is distinct from **Learn more**: it carries the reader along a defined sequence, while **Learn more** stays optional. It also avoids the "steps" mobility metaphor, so the ban on **Next steps** still holds. @@ -290,7 +291,8 @@ Now that you added a language, [install your own command-line tools](./install-c - [Parameters](../../admin/templates/extending-templates/parameters.md) in the Coder documentation ``` -*Enforced by `Coder.LearnMore` (planned). The planned rule flags Next steps, not What's next?.* +*Enforced by `Coder.LearnMore` (planned). +The planned rule flags **Next steps** only.* ## Tutorial, not walkthrough @@ -315,7 +317,7 @@ Use "select" for actions on UI elements, regardless of input device. Touch devices tap, keyboard users press Enter, and assistive-technology users activate. "Select" covers every case and matches the Microsoft style guide convention. -Reserve "click" for code or configuration that literally fires on a click event, like a `onClick` handler or a DOM `click` event. +Reserve "click" for code or configuration that literally fires on a click event, like an `onClick` handler or a DOM `click` event. **Do**: @@ -333,11 +335,11 @@ Reserve "click" for code or configuration that literally fires on a click event, ## Don't assume simplicity or difficulty -Words that minimize the difficulty of an action ("simply", "just", "easy", "easily", "obviously", "of course", "clearly") assume the reader's experience matches the author's. +Words that minimize the difficulty of an action ("simply," "just," "easy," "easily," "obviously," "of course," "clearly") assume the reader's experience matches the author's. If something is "obvious" to the author and not to the reader, the reader may feel the document is confusing or condescending. Cut the simplicity-assuming word or restructure the sentence. -The reverse pattern, exaggerating difficulty ("complex", "intricate", "non-trivial"), is also banned. +The reverse pattern, exaggerating difficulty ("complex," "intricate," "non-trivial"), is also banned. Both patterns predict the reader's reaction instead of describing the work. **Do**: @@ -355,10 +357,10 @@ Both patterns predict the reader's reaction instead of describing the work. ## Avoid weasel words -Vague attributions ("many believe", "some say", "experts agree", "studies show", "it is widely accepted that", "most people") let the prose claim something without naming a source. +Vague attributions ("many believe," "some say," "experts agree," "studies show," "it is widely accepted that," "most people") let the prose claim something without naming a source. Either name the source or remove the claim. -Vague qualifiers ("often", "usually", "sometimes", "in most cases") tell the reader the statement is sometimes false but don't say when. +Vague qualifiers ("often," "usually," "sometimes," "in most cases") tell the reader the statement is sometimes false but don't say when. Replace with the specific condition, or remove the qualifier and accept the statement as a default. **Do**: @@ -453,7 +455,7 @@ The published page stays the same for everyone. *Documentation-only. Planned Vale rule `Coder.InternalReferences`.* -## Related +## Learn more - [Style guide landing page](./README.md) - [Voice and tone](./voice-and-tone.md)