diff --git a/docs/.style/style-guide/README.md b/docs/.style/style-guide/README.md index 10ba7c1875d..f32d938cab2 100644 --- a/docs/.style/style-guide/README.md +++ b/docs/.style/style-guide/README.md @@ -2,16 +2,16 @@ This is the canonical prose style guide for the Coder documentation. It tells you *how* to write the words that go in the docs. -For decisions about what belongs in the docs and what does not, refer to [`content-guidelines.md`](../content-guidelines.md). +For decisions about what belongs in the docs and what doesn't, refer to [`content-guidelines.md`](../content-guidelines.md). -Each rule on the pages below is a policy decision the Coder docs team has made. +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). ## How to use this guide -- **Contributors**: read the section that matches what you are writing. +- **Contributors**: read the section that matches what you're writing. Each rule includes a brief rationale and **Do** / **Don't** examples. - **Reviewers**: cite the section in a review comment. Reviews are easier when the guidance lives in one place. @@ -40,9 +40,9 @@ The style guide subpages dogfood them so contributors can see the rules in actio Source lines in Coder documentation follow a one-sentence-per-line policy. Each sentence sits on its own Markdown source line. -Sentences are not split across lines, and lines do not wrap to a fixed column width. +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 do not appear in the rendered output. +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. `markdownlint`'s `MD013` (line length) is already disabled, so the convention is editorial. @@ -55,12 +55,12 @@ Much of the existing prose still wraps to a fixed column width or runs on a sing 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. -The contributor does not reformat surrounding paragraphs they did not otherwise touch. +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`. -### The style guide does not use "see" for navigation +### The style guide doesn't use "see" for navigation The [Word choice page](./word-choice.md) bans "see" as a navigational verb across all docs. The style guide itself follows the rule: "refer to" for formal cross-references, "check out" for informal pointers in tutorial-style passages, "visit" for external URLs. @@ -69,7 +69,7 @@ Reserve "see" for the rare case where the prose describes what a reader observes ## Vale enforcement The repo-root `.vale.ini` loads only the Coder rule package by default. -Third-party rules from Google, alex, and write-good are not enabled until a per-rule PR brings each back in. +Third-party rules from Google, alex, and write-good aren't enabled until a per-rule PR brings each back in. Each enabled rule lands via a dedicated PR that: @@ -93,13 +93,13 @@ Run `make lint/prose` to reproduce the baseline locally. A public-facing prose summary lives today at [`docs/about/contributing/documentation.md`](../../about/contributing/documentation.md). A follow-up PR will redirect that page to this guide. -Until then, follow the public summary for anything the subpages of this guide do not cover. +Until then, follow the public summary for anything the subpages of this guide don't cover. New prose rules land here. The public page is frozen pending the redirect. ## Third-party references -When this guide does not cover something, consult: +When this guide doesn't cover something, consult: | Type of guidance | Reference | |--------------------------|-----------------------------------------------------------------------------------------| diff --git a/docs/.style/style-guide/accessibility-and-inclusion.md b/docs/.style/style-guide/accessibility-and-inclusion.md index ac5849ba8c8..acf71a19a60 100644 --- a/docs/.style/style-guide/accessibility-and-inclusion.md +++ b/docs/.style/style-guide/accessibility-and-inclusion.md @@ -1,6 +1,6 @@ # 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 does not 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 as a stretch goal where 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. @@ -10,14 +10,14 @@ They cover heading structure, inclusive language, link text, images, plain Engli ## Heading structure and placement Each page has exactly one H1. -The H1 is the page title and appears once at the top of the page. +The H1 is the page title and appears once at the beginning of the page. Subsequent headings descend by one level at a time. A page goes H1, then H2, then H3. -A page does not jump from H2 to H4. +A page doesn't jump from H2 to H4. Each heading is followed by at least one paragraph (or other content block) before the next heading. A bare H2 followed immediately by an H3 with no prose in between reads as a broken document outline, and SEO crawlers flag the pattern as a potential site error. -If a parent heading does not yet have introductory content, write a short paragraph that frames what the section covers before the subheadings. +If a parent heading doesn't yet have introductory content, write a short paragraph that frames what the section covers before the subheadings. The rule is a [WCAG 2.1 Level A](https://www.w3.org/TR/WCAG21/#info-and-relationships) requirement: assistive technology relies on heading levels to convey document structure. Skipping a level breaks the outline. @@ -28,12 +28,12 @@ Skipping a level breaks the outline. # Configure your workspace This page walks through the configuration options exposed on a Coder workspace. -The sections below cover SSH access and environment variables. +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 below. +Two client setups are documented in the following sections. ### Connect through JetBrains Toolbox @@ -123,8 +123,8 @@ Screen readers announce link text out of context too, which is the [WCAG 2.1 Lev Every image declares descriptive alt text. The alt text describes what the image shows or what purpose it serves. -It is not a caption. -Captions go below the image in a `` tag. +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". @@ -132,10 +132,10 @@ Lead with the subject, not "An image of" or "A screenshot showing". ```markdown ![Template Insights dashboard with weekly active users and connection latency charts](../../images/admin/templates/template-insights.png) -The Template Insights dashboard. Active users in the left panel; connection latency in the right panel. +The Template Insights dashboard with active-user and connection-latency widgets. ``` -For complex diagrams that cannot be summarized in alt text, provide a longer description in the body of the page and reference it from the alt text. +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. *Enforced by `markdownlint` rule `MD045` for the alt-text-required requirement.* @@ -155,14 +155,57 @@ When in doubt, write descriptive alt text. *Documentation-only. 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. +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. +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. +> +> Add a `` caption after the image. +> +> Open the **Workspaces** sidebar to switch templates. + +**Don't**: + +> See the table below for the comma convention. +> +> Add a `` caption underneath the image. +> +> Open the menu on the left to switch templates. + +Common replacements: + +| Avoid | Prefer | +|------------------------------|---------------------------------------------------------| +| see below | see the following section, see the `[Section](#anchor)` | +| see above | see the previous section, see earlier | +| top of the page | beginning of the page | +| bottom of the page | end of the page | +| the menu on the left | the **Sidebar** menu | +| the right side of the screen | the **Details** panel | +| scroll down | scroll to the `[Section](#anchor)`, scroll to the end | + +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. + +*Documentation-only. +No Vale rule.* + ## Plain English for international readers -Keep prose accessible to readers whose first language is not English. +Keep prose accessible to readers whose first language isn't English. Two patterns add friction for non-native speakers without adding meaning, so the guide bans them: ### 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 does not translate. +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. Replace them with the literal meaning. @@ -190,13 +233,13 @@ Planned Vale rule `Coder.Idioms`.* The following Latin abbreviations are fine in Coder docs. Use them when they fit the sentence; the English equivalent is also fine. -| Abbreviation | Meaning | Notes | -|--------------|------------------------------------------------|--------------------------------------------------------------------------------| -| `e.g.` | for example | Followed by a comma. Prefer parentheses around the clause, as described below. | -| `i.e.` | that is | Followed by a comma. Prefer parentheses around the clause, as described below. | -| `etc.` | and so on | Closes a list. The Oxford comma applies before it: `apples, oranges, etc.` | -| `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. | +| Abbreviation | Meaning | Notes | +|--------------|------------------------------------------------|----------------------------------------------------------------------------| +| `e.g.` | for example | Followed by a comma. Prefer parentheses around the clause. | +| `i.e.` | that is | Followed by a comma. Prefer parentheses around the clause. | +| `etc.` | and so on | Closes a list. The Oxford comma applies before it: `apples, oranges, etc.` | +| `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. @@ -241,7 +284,7 @@ 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 are not 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 many readers and easy to misuse. Replace them with plain English. **Don't**: @@ -274,7 +317,7 @@ A page's H1 and its sidebar title serve different jobs and may diverge. It fits the limited horizontal space of the sidebar and reads fast when the reader is scanning a tree of dozens of pages. 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 do not need to be identical. +The two must each stand alone, but they don't need to be identical. Breadcrumb depth gives one layer of context for free. The sidebar title can drop redundancy that the parent breadcrumbs already imply. @@ -283,7 +326,7 @@ A page reachable through **Administration** > **Authentication** > **Google** ha 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 is fine. +When the H1 and the sidebar title coincide (often the case 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. @@ -306,7 +349,7 @@ AWS, Microsoft Learn, and GitHub Docs all pair task-focused H1s with shorter nou The first **Don't** row uses the full H1 as the sidebar title. The sidebar title is redundant with the parent breadcrumbs and crowds the navigation tree. -The second row has a sidebar title that does not stand alone. +The second row has a sidebar title that doesn't stand alone. The third row has a sidebar title that tells the reader nothing. *Documentation-only. @@ -329,7 +372,7 @@ The manifest maps each page to a `title` and a `description`: A good description: - States what the page covers in one sentence. -- Stays under roughly 160 characters so search engines do not truncate it. +- Stays under roughly 160 characters so search engines don't truncate it. - Avoids marketing language and superlatives. - Reads as a complete sentence. @@ -350,9 +393,9 @@ A good description: ``` The short description tells the reader nothing. -The marketing description does not survive truncation and adds no information. +The marketing description doesn't survive truncation and adds no information. -If a page does not yet have a description in the manifest, add one in the same PR that touches the page. +If a page doesn't yet have a description in the manifest, add one in the same PR that touches the page. *Documentation-only. No Vale rule.* @@ -378,8 +421,8 @@ The criterion is satisfied either by writing at the lower-secondary reading leve 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. -The grade level is not a hard ceiling. -A reference page that requires technical vocabulary will read higher than a tutorial, and that is correct. +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. *Documentation-only. No Vale rule wired.* diff --git a/docs/.style/style-guide/audience-and-scope.md b/docs/.style/style-guide/audience-and-scope.md index 20970b96e10..03247efadbe 100644 --- a/docs/.style/style-guide/audience-and-scope.md +++ b/docs/.style/style-guide/audience-and-scope.md @@ -5,7 +5,7 @@ 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 does not 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, 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. The single canonical Coder example is **install Coder**. An end user wants to connect their local editor to a Coder workspace and start coding. @@ -25,7 +25,7 @@ The audience determines: If a topic genuinely needs to serve two audiences, write two pages and cross-link them. Resist the temptation to write one page with audience-tagged sections. -Section tags do not save readers from scanning content that does not apply to them. +Section tags don't save readers from scanning content that doesn't apply to them. **Do**: @@ -45,7 +45,7 @@ For Windsurf, refer to [Windsurf](./windsurf.md). # Connect to your Coder workspace This page covers Visual Studio Code, Cursor, Windsurf, JetBrains, Vim, the web terminal, and SSH. -Operators provisioning the workspace template should refer to the section below on template configuration. +Operators provisioning the workspace template should refer to the template configuration page. ``` ## Pick one outcome per page @@ -58,9 +58,9 @@ An overview page introduces one concept. If the page has more than one outcome, split it. "Configure SSO with Okta" is one outcome. -"Configure SSO" is not. +"Configure SSO" isn't. "Deploy Coder on AWS" is one outcome. -"Deploy Coder" is not. +"Deploy Coder" isn't. A page that helps the reader accomplish two unrelated outcomes hides each outcome from the readers who need the other. @@ -88,7 +88,7 @@ SAML providers, GitHub OAuth, password authentication, and the API token model. Some pages exist to orient the reader and route them to the child page that owns the actual content. A hub page may have a broad title and a short body when its job is to direct the reader to a child page, not to teach. -Hub pages are not an exemption from the audience and outcome rules. +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. @@ -131,8 +131,8 @@ This page covers OIDC, SAML, GitHub OAuth, password authentication, and the API 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. -A hub page does not 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 is where the reader's next step lives. +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. ## Declare audience and scope up front @@ -145,7 +145,7 @@ Conventions: - The first paragraph names the audience and confirms the outcome. - The first paragraph also links to sibling pages for adjacent audiences or outcomes when those exist. -Do not put a metadata line such as `*Audience: a developer.*` above the first paragraph. +Do not put a metadata line such as `*Audience: a developer.*` before the first paragraph. The audience appears in the prose itself. Do not use the [persona names](#personas-the-coder-docs-serve) inside the page body either. Persona names are vocabulary for writers planning the page, not for readers reading it. @@ -171,8 +171,8 @@ Coder runs on Kubernetes. This page covers many topics related to running Coder on Kubernetes. ``` -The Don't title does not name an outcome. -The body does not name an audience. +The Don't title doesn't name an outcome. +The body doesn't name an audience. If the page is a hub that routes the reader, use the pattern in [Hub pages and category landing pages](#hub-pages-and-category-landing-pages). If the page teaches a single outcome, rename the title and rewrite the opening paragraph. @@ -181,7 +181,7 @@ If the page teaches a single outcome, rename the title and rewrite the opening p Some pages walk through steps that only one role should run. If a reader from the wrong role follows the steps, they may misconfigure the deployment, escalate their own permissions, or break something for everyone else. -For pages of that kind, add an `IMPORTANT` callout at the top of the page that names the required role and tells the wrong-role reader who to ask. +For pages of that kind, add an `IMPORTANT` callout at the beginning of the page that names the required role and tells the wrong-role reader who to ask. **Do**: @@ -193,7 +193,7 @@ 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 are not a deployment administrator, +> If you aren't a deployment administrator, > ask your administrator to complete the steps for you. ``` @@ -206,8 +206,8 @@ 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. -Do not hedge a step with "ask your administrator" or "if you have permission". -Those caveats are written for a reader this page does not target, and they make the real reader doubt whether the step is meant for them. +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: @@ -224,7 +224,7 @@ If the caveat serves a different audience, cut it, or move it to the page that a **Don't**: > Configure a GitHub provider on your deployment. -> If you are not a deployment administrator, ask your administrator to do this for you. +> If you aren't a deployment administrator, ask your administrator to do this for you. The **Don't** aside is correct on an enterprise how-to page, where the reader may not own the deployment. On a Quickstart that walked the same reader through starting the server, the reader already has the access, so the aside only adds doubt. @@ -237,11 +237,11 @@ This is the complement of [gating privileged pages](#gate-privileged-pages-with- When deciding which audience a page targets, match the reader to one of the canonical personas the Coder docs serve. Each persona summary captures who the reader is, what they need from the docs, and the Coder surface they typically work with. -If a page does not cleanly target one of these personas, revisit the scope. +If a page doesn't cleanly target one of these personas, revisit the scope. A page without a clear persona is a page that serves no one well. The persona names are vocabulary for writers planning a page. -They do not appear in published prose. +They don't appear in published prose. Inside a page, name the audience by the role the reader recognizes from their own work (`developer`, `template author`, `Coder deployment administrator`). ### Primary personas @@ -257,17 +257,17 @@ They need template authoring docs, RBAC and organization design, integration pat #### Dave the Developer Dave is a software engineer at a company that has adopted Coder. -They were not involved in the procurement decision and are expected to use the workspace the company provisioned for them. +They weren't involved in the procurement decision and are expected to use the workspace the company provisioned for them. They need day-to-day workspace usage docs: connecting from their preferred IDE, running CLI commands inside the workspace, port forwarding, SSH, and recovering when something breaks. *Coder surface:* workspaces, `coder` CLI, IDE integrations (VS Code, Cursor, JetBrains, Windsurf, Zed, Vim, Emacs), web terminal, dotfiles, SSH and port forwarding. #### Elliot the End User -Elliot uses a Coder workspace day-to-day but is not a software engineer. +Elliot uses a Coder workspace day-to-day but isn't a software engineer. They may be a data scientist, product manager, customer success engineer, operations analyst, or another team member whose primary work happens inside a workspace the organization provisioned for them. They need workspace-usage docs in plain language: connecting to the workspace, running the tools their team has standardized on, and recovering when something breaks. -They do not need template authoring or infrastructure context. +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. @@ -336,7 +336,7 @@ They are skeptical of new tools by default and want documented, auditable behavi Tara is an engineering manager or senior tech lead assigned the Group Admin role in Coder RBAC. They need docs for team-scope administration: group memberships, group-owned secrets, group-scoped templates, and the audit log entries that explain who changed what. -They are not the platform owner. +They aren't the platform owner. They run their team inside the guardrails Perry or Ada set up. *Coder surface:* groups, group memberships, group-owned secrets, group-scoped templates, group audit logs. diff --git a/docs/.style/style-guide/capitalization-and-punctuation.md b/docs/.style/style-guide/capitalization-and-punctuation.md index 928638d444a..087b7239c0f 100644 --- a/docs/.style/style-guide/capitalization-and-punctuation.md +++ b/docs/.style/style-guide/capitalization-and-punctuation.md @@ -64,7 +64,7 @@ The rule targets verb forms (`installing`, `configuring`, `deploying`), not the When the `-ing` word is the actual subject the section describes (a feature, a noun, or an attribute), the heading is fine. When the `-ing` word is the verb form of a task the section walks through, rewrite as an imperative or as the noun form. -*Enforced by `Coder.GerundHeading`, with the exceptions above scoped in the rule.* +*Enforced by `Coder.GerundHeading`, with the exceptions listed earlier scoped in the rule.* ## No trailing punctuation in headings @@ -81,7 +81,7 @@ The rule has scoped exceptions: **Do**: ```markdown -## What is a workspace +## What's a workspace ## Quick reference ## What does the `panic!` macro do? ## Configure the `.vale.ini` file @@ -90,13 +90,13 @@ The rule has scoped exceptions: **Don't**: ```markdown -## What is a workspace? +## What's a workspace? ## Quick reference! ## Workspaces are great! ## Configure your workspace. ``` -The first **Don't** uses a trailing question mark for a label that is not actually a question. +The first **Don't** uses a trailing question mark for a label that isn't actually a question. Reword as a noun phrase ("What a workspace is") or drop the question mark. The second and third are decorative. The fourth treats the heading as a sentence. @@ -154,7 +154,7 @@ No Vale rule.* ### No comma in a short compound predicate -When `and`, `or`, or `but` joins two verbs that share one subject, do not put a comma before the conjunction. +When `and`, `or`, or `but` joins two verbs that share one subject, don't put a comma before the conjunction. The comma belongs there only when the conjunction joins two independent clauses, each with its own subject. **Do**: @@ -209,7 +209,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 are 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 almost always read more clearly. **Do**: diff --git a/docs/.style/style-guide/formatting.md b/docs/.style/style-guide/formatting.md index e966aa99d18..f18429296c2 100644 --- a/docs/.style/style-guide/formatting.md +++ b/docs/.style/style-guide/formatting.md @@ -10,7 +10,7 @@ The accessibility-driven rules live on that page so heading structure, language, ## One sentence per line Write each sentence on its own Markdown source line. -Do not split a sentence across multiple lines, and do not wrap to a fixed column width. +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. A sentence-level edit changes one line, not a paragraph reflow, so reviewers see exactly which sentence moved. @@ -21,7 +21,7 @@ What counts as a single line: - One declarative, interrogative, or imperative sentence ending in a period, question mark, or exclamation point. - The full text of a single bullet item, numbered list entry, or blockquote line. -What does not get its own line: +What doesn't get its own line: - Mid-sentence clauses or phrases. - Source inside fenced code blocks, where the language's own conventions apply. @@ -111,14 +111,14 @@ Use backticks (inline code font) for the following: > Run `coder login --token ` to authenticate. > Set `CODER_URL` in your environment first. > -> The server returns `404 Not Found` when the workspace does not exist. +> The server returns `404 Not Found` when the workspace doesn't exist. **Don't**: > Run "coder login --token \" to authenticate. > Set CODER_URL in your environment first. > -> The server returns 404 when the workspace does not exist. +> The server returns 404 when the workspace doesn't exist. *Documentation-only. No Vale rule.* @@ -133,7 +133,7 @@ Every fenced code block declares a language. Use the most specific language tag available: - `sh` for a shell command or a shell script. - Use `sh` when the block is input the reader types or a script they save, and the block does not also show output. + Use `sh` when the block is input the reader types or a script they save, and the block doesn't also show output. - `console` for an interactive session that shows the typed command and its output together. Prefix each typed line with `$`. - `powershell` for Windows command-line blocks. @@ -195,11 +195,11 @@ Prose should carry the message. | Callout | Use for | |------------------|----------------------------------------------------------------------------------------------------------------------| -| `> [!NOTE]` | Supplementary context the reader benefits from but does not need to act on before proceeding | +| `> [!NOTE]` | Supplementary context the reader benefits from but doesn't need to act on before proceeding | | `> [!TIP]` | An optional optimization, shortcut, or related feature | | `> [!IMPORTANT]` | A required step or prerequisite the reader will miss if they skim | | `> [!WARNING]` | An action with a serious side effect (data loss, downtime, security exposure) that the reader must read before doing | -| `> [!CAUTION]` | A severe or irreversible consequence; reserve for cases where `WARNING` is not strong enough | +| `> [!CAUTION]` | A severe or irreversible consequence; reserve for cases where `WARNING` isn't strong enough | A follow-up PR will demonstrate each callout rendered against an existing docs page so reviewers can calibrate when each one fits. @@ -381,12 +381,12 @@ Place image assets under the matching subdirectory of `docs/images/`. Use lowercase filenames with hyphens between words (`template-insights-dashboard.png`). Reference the asset with a relative path from the Markdown source. -Captions go below the image in a `` tag. +Captions follow the image in a `` tag. ```markdown ![Template Insights dashboard with weekly active users and connection latency charts](../../images/admin/templates/template-insights.png) -The Template Insights dashboard. Active users in the left panel; connection latency in the right panel. +The Template Insights dashboard with active-user and connection-latency widgets. ``` For alt text and decorative-image conventions, refer to [Alt text for images](./accessibility-and-inclusion.md#alt-text-for-images) and [Decorative images](./accessibility-and-inclusion.md#decorative-images). @@ -405,7 +405,7 @@ A worked example, a code block, or a precise written instruction is almost alway 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 cannot use the screenshot at all. +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 writer who adds a screenshot owns the cost of replacing it every time the captured surface changes. When a screenshot is the right answer: @@ -426,7 +426,7 @@ When a screenshot is the right answer: > ![Workspace settings page with Autostart set to Weekdays at 9 AM](../../images/workspaces/autostart.png) > -> Configure autostart as shown above. +> Configure autostart as shown in the screenshot. The authoritative screenshot policy, including the obfuscation, PHI, and PII rules, lives in [`content-guidelines.md`](../content-guidelines.md). diff --git a/docs/.style/style-guide/numbers-units-and-dates.md b/docs/.style/style-guide/numbers-units-and-dates.md index 294d7b86c7d..e2aae026652 100644 --- a/docs/.style/style-guide/numbers-units-and-dates.md +++ b/docs/.style/style-guide/numbers-units-and-dates.md @@ -80,7 +80,7 @@ The non-breaking-space rule applies to prose only. ## Date format Write dates as `Month Day, Year` with a full month name and a comma between day and year. -The format is unambiguous across locales, which the all-numeric forms (`07/31/2026` versus `31/07/2026`) are not. +The format is unambiguous across locales, which the all-numeric forms (`07/31/2026` versus `31/07/2026`) aren't. **Do**: @@ -121,7 +121,8 @@ The 12-hour rule is for prose only. ## Ordinals Spell out ordinals `first` through `ninth`. -Use digits with a suffix for `10th` and up. This is the one place the digits-everywhere rule yields, because ordinals spelled out read more naturally in prose at low counts. +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. **Do**: diff --git a/docs/.style/style-guide/voice-and-tone.md b/docs/.style/style-guide/voice-and-tone.md index 0fd43d16e04..a19b25cf6d5 100644 --- a/docs/.style/style-guide/voice-and-tone.md +++ b/docs/.style/style-guide/voice-and-tone.md @@ -12,7 +12,7 @@ Second person is direct, scales across audiences, and avoids the ambiguity of "t **Do**: -> You can connect to a workspace over SSH after you have installed the Coder CLI. +> You can connect to a workspace over SSH after you've installed the Coder CLI. **Don't**: @@ -94,7 +94,7 @@ Imprecise rules like `Google.Passive` and `write-good.Passive` fire on every pas ## Present tense by default Describe how the product works in the present tense. -Future tense ("will") implies an event that has not happened yet at read time. +Future tense ("will") implies an event that hasn't happened yet at read time. Reserve future tense for: - Genuine future events, like scheduled rollouts or deprecations with a known date. @@ -119,11 +119,78 @@ Use plain present tense for behavior the product already exhibits. *Documentation-only. No Vale rule.* +## Contractions are the default + +Contractions match how a reader's internal voice sounds. +Prefer them in body prose for the same reason the docs use second person and present tense. +Expand a contraction only when one of the following exceptions applies. + +**Do**: + +> Coder doesn't restart workspaces on minor template updates. +> +> If you're using PostgreSQL, set the connection string before starting `coder server`. + +**Don't**: + +> Coder does not restart workspaces on minor template updates. +> +> 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. +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. + +**Do**: + +> Restart the workspace if you want. +> +> The agent reattaches whenever a workspace exists. + +**Don't**: + +> Restart the workspace if you'd. +> +> 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. +Expand one of the two contractions, keeping whichever reads more naturally in context. + +**Do**: + +> If you would've finished the upgrade earlier, the migration wouldn't have failed. +> +> If you'd have finished the upgrade earlier, the migration wouldn't have failed. + +**Don't**: + +> 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`. +The contracted forms read fast and let a busy reader skip past the warning. + +**Do**: + +> Do not delete the workspace before backing up its state. +> Coder cannot restore a deleted workspace. +> +> You cannot undo `coder delete`. + +**Don't**: + +> Don't delete the workspace before backing up its state. +> Coder can't restore a deleted workspace. +> +> You can't undo `coder delete`. + +*Documentation-only. +No Vale rule.* + ## Trailing prepositions are a judgment call 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 is no one-size-fits-all rule. +There's no one-size-fits-all rule. 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: diff --git a/docs/.style/style-guide/word-choice.md b/docs/.style/style-guide/word-choice.md index 08e3b6ea4a0..307d076502c 100644 --- a/docs/.style/style-guide/word-choice.md +++ b/docs/.style/style-guide/word-choice.md @@ -74,7 +74,7 @@ The open standard at [containers.dev](https://containers.dev/) uses two forms in The Coder docs follow the same conventions. `envbuilder` is the implementation tool Coder uses to build dev containers. -It is not itself the concept, so it stays in backticks as a tool name. +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. > 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. @@ -159,7 +159,7 @@ When the prose points the reader at another page, section, or external resource, Do not use **see** as a navigational verb. Reserve **see** for the rare case where the prose describes what a reader observes in the product UI ("You see a list of templates on the Templates page"). -The plain-language alternatives carry register information that "see" does not, and reserving "see" for its observational meaning improves clarity for every reader. +The plain-language alternatives carry register information that "see" doesn't, and reserving "see" for its observational meaning improves clarity for every reader. 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. @@ -173,7 +173,7 @@ In a list of outcomes, "learn why the build fails" or "find out why the build fa > > Visit the [Terraform Registry](https://registry.terraform.io/) for the latest provider versions. > -> Add a Ruby option, then learn why the option alone does not install the toolchain. +> Add a Ruby option, then learn why the option alone doesn't install the toolchain. **Don't**: @@ -183,7 +183,7 @@ In a list of outcomes, "learn why the build fails" or "find out why the build fa > > See the [Terraform Registry](https://registry.terraform.io/) for the latest provider versions. > -> Add a Ruby option, then see why the option alone does not install the toolchain. +> Add a Ruby option, then see why the option alone doesn't install the toolchain. *Enforced by `Coder.SeeAlternatives` (planned).* @@ -195,8 +195,8 @@ Two rationales apply: - **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). - **Inclusive language**: "steps" reads as a physical-mobility metaphor. - Readers who cannot walk through steps still consume technical documentation. - Neutral alternatives like "Learn more" do not encode that assumption. + Readers who can't walk through steps still consume technical documentation. + Neutral alternatives like "Learn more" don't encode that assumption. **Do**: @@ -222,7 +222,7 @@ Two rationales apply: `Tutorial` is the standard term in technical documentation and matches the Diátaxis category. `Walkthrough` is colloquial, and the metaphor assumes the reader can walk. -Neutral alternatives like "tutorial" do not encode that assumption. +Neutral alternatives like "tutorial" don't encode that assumption. **Do**: @@ -284,7 +284,7 @@ Both patterns predict the reader's reaction instead of describing the work. 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 do not 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**: @@ -308,7 +308,7 @@ Replace with the specific condition, or remove the qualifier and accept the stat ## Stop, not kill; turn off, not disable In product-facing prose, prefer "stop" over "kill" and "turn off" over "disable". -The plain-language forms read better for a non-technical audience and do not carry violent or ableist connotations. +The plain-language forms read better for a non-technical audience and don't carry violent or ableist connotations. The rule has scoped exceptions for unavoidable industry-specific terms. When the prose names a specific technical command or a real state label, the original term is the only correct one. @@ -354,7 +354,7 @@ A dedicated rule for `run` is out of scope for this revision. The published documentation, including the contribution guides, is public. Every reader and every contributor, whether a community contributor or a Coder employee, must be able to open every resource linked from the docs. -A link that only employees can open excludes community contributors, so it does not belong on a published page. +A link that only employees can open excludes community contributors, so it doesn't belong on a published page. Keep these out of published pages: