diff --git a/.vale.ini b/.vale.ini index a7a618fad12a1..2fd46db96a94f 100644 --- a/.vale.ini +++ b/.vale.ini @@ -48,10 +48,12 @@ Google.EmDash = NO # produces noise without value. Google.Latin = NO -# Soften two high-volume Google rules. The signal-to-noise ratio is low -# at the default warning level. -Google.Parens = suggestion -Google.WordList = warning +# Google.Parens flags every paren use as "use parentheses judiciously." +# Parens are a normal English punctuation device for clarification, +# examples, and disambiguation. The rule cannot distinguish stylistic +# intent from misuse, so even at suggestion level its signal-to-noise +# ratio is effectively zero. Disable. +Google.Parens = NO # Google.Spacing flags fully-qualified Go type names like # `codersdk.WorkspaceAgent` as "should have one space." It produces ~4,500 @@ -64,6 +66,11 @@ Google.WordList = warning # `error`. Google.Spacing = NO +# Google.WordList is the canonical Google word-substitution table. Keep +# at warning (the default for the Google package) so non-canonical word +# choices surface as CI annotations. +Google.WordList = warning + # --- write-good curation --------------------------------------------------- # Passive voice is contextually correct often enough that flagging every # instance teaches nothing. E-Prime forbids forms of "to be" entirely, diff --git a/docs/.style/style-guide.md b/docs/.style/style-guide.md index 1065287a86863..e7b141d516596 100644 --- a/docs/.style/style-guide.md +++ b/docs/.style/style-guide.md @@ -1,54 +1,65 @@ # Coder documentation style guide -This is the canonical style guide for the Coder documentation. It is the -source of truth that the Vale rules in `docs/.style/styles/Coder/` enforce. +This is the canonical style guide for the Coder documentation. +It's the source of truth that the Vale rules in `docs/.style/styles/Coder/` enforce. -Status: scaffold. Sections below are populated by follow-up PRs; this -page starts as a table of contents and grows as those PRs land. +Status: scaffold. +Follow-up PRs populate the sections below. +This page starts as a table of contents and grows as those PRs land. ## How to use this guide -This page is a scaffold while follow-up PRs land. Sections marked "To be -filled in" are placeholders. For anything not yet covered, see the -public summary at -[`docs/about/contributing/documentation.md`](../about/contributing/documentation.md). +This page is a scaffold while follow-up PRs land. +Sections marked "Coming in follow-up PRs" are placeholders. +For anything not yet covered, see the public summary at [`docs/about/contributing/documentation.md`](../about/contributing/documentation.md). - **Contributors**: read the section that matches what you are writing. - Each rule notes the Vale rule ID, if any, so you can reproduce the - warning locally. -- **Reviewers**: cite the section in a review comment. Reviews are easier - when the guidance is in one place. -- **AI agents**: read this page in full before editing anything under - `docs/`. The Coder Agents and Claude Code guides - ([`AGENTS.md`](../../AGENTS.md), - [`.claude/docs/DOCS_STYLE_GUIDE.md`](../../.claude/docs/DOCS_STYLE_GUIDE.md)) - link here. + Each rule notes the Vale rule ID, if any, so you can reproduce the warning locally. +- **Reviewers**: cite the section in a review comment. + Reviews are easier when the guidance is in one place. +- **AI agents**: read this page in full before editing anything under `docs/`. + The Coder Agents and Claude Code guides ([`AGENTS.md`](../../AGENTS.md), [`.claude/docs/DOCS_STYLE_GUIDE.md`](../../.claude/docs/DOCS_STYLE_GUIDE.md)) link here. ## Voice and tone -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Active voice - Second person - Plural nouns and pronouns where number is uncertain -- Product voice (`stop` over `kill`, `turn off` over `disable` in - user-facing copy) -- Limiting "we" +- Product voice (`stop` over `kill`, `turn off` over `disable` in user-facing copy) +- Limit `we` ## Word choice -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Inclusive-language substitutions -- HashiCorp casing - Dev Container terminology - "Setup" vs "set up" and Quickstart casing - "Next steps" vs "Learn more" - Weasel words +### Brand names + +Use each brand's canonical casing in prose. +URLs and code references (Terraform provider source addresses, GitHub paths) keep the lowercase form their owner uses. +Vale's `substitution` rule skips inline code and links by default, so those aren't affected. + +| Wrong | Correct | Notes | +|-------------|-------------|-----------------------------------| +| `Hashicorp` | `HashiCorp` | Mixed case: capital H, capital C. | + +More brands (GitHub, OpenTofu, Kubernetes, Terraform, JetBrains, VS Code) extend this table as they land in follow-up PRs. + +Enforced by `Coder.BrandNames` (level `error`). +To add a brand: append a swap to `docs/.style/styles/Coder/BrandNames.yml`, +run `make lint/prose` to catch existing-content violations, +fix them, then commit. + ## Capitalization and punctuation -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Sentence case in titles and headings - General capitalization policy @@ -56,46 +67,40 @@ To be filled in by follow-up PRs. Planned coverage: ## Formatting -To be filled in by follow-up PRs. Planned coverage: +Coming in follow-up PRs: - Bold for UI elements - Italics for parameter names and version variables -- Code font for user input, command-line utility names, filenames, - environment variables, HTTP verbs and status codes, placeholder - variables +- Code font for user input, command-line utility names, filenames, environment variables, HTTP verbs and status codes, placeholder variables - Code blocks with explicit language fences ## Vale enforcement -The repo-root `.vale.ini` configures Vale to read styles from -`docs/.style/styles/`. The starter configuration combines: +The repo-root `.vale.ini` configures Vale to read styles from `docs/.style/styles/`. +The starter configuration combines: - Google's developer-docs base style - A curated subset of `alex` (inclusive-language) - A curated subset of `write-good` (wordiness) - Coder-specific custom rules in `docs/.style/styles/Coder/` -The rationale for the cherry-picked base styles and the severity -policy lives in `.vale.ini`'s inline comments. Run `make lint/prose` -to reproduce the baseline locally. +The rationale for the cherry-picked base styles and the severity policy lives in `.vale.ini`'s inline comments. +Run `make lint/prose` to reproduce the baseline locally. ## Editor setup -To be filled in by a follow-up PR. Will cover VS Code, Cursor, -JetBrains, and Neovim. +A follow-up PR adds coverage for VS Code, Cursor, JetBrains, and Neovim. ## Relationship to `docs/about/contributing/documentation.md` -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 scaffolded sections above do -not yet cover. New prose rules land here; the public page is frozen -pending the redirect. +A public-facing prose summary lives today at [`docs/about/contributing/documentation.md`](../about/contributing/documentation.md). +A follow-up PR redirects that page to this guide. +Until then, follow the public summary for anything the scaffolded sections in this guide don't yet 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/styles/Coder/BrandNames.yml b/docs/.style/styles/Coder/BrandNames.yml new file mode 100644 index 0000000000000..a5a73f61bbad2 --- /dev/null +++ b/docs/.style/styles/Coder/BrandNames.yml @@ -0,0 +1,28 @@ +# Coder.BrandNames - enforce canonical brand-name casing in prose. +# +# Vale's substitution rule applies in prose only; it skips fenced code +# blocks, inline code, and URLs by default. That means `hashicorp/kubernetes` +# (Terraform provider source) and `developer.hashicorp.com` (URL) stay +# untouched. The rule fires on body text and headings where the wrong +# casing appears as a normal word. +# +# Level: error. Each swap targets a brand whose owner publishes a +# canonical casing; "Hashicorp Vault" instead of "HashiCorp Vault" is +# objectively wrong, not a judgment call. The existing-content violation +# count is zero (cleanup landed in the previous commit), so this rule +# can ship at error from day one. +# +# Adding a brand: append a key/value to the swap table below and audit +# the docs corpus for the wrong-casing variant. Keep the message template +# unchanged; the `%s` token interpolates the matched (wrong) text. +extends: substitution +message: "Use '%s' instead of '%s' (brand-name casing)." +link: https://github.com/coder/coder/blob/main/docs/.style/style-guide.md#brand-names +level: error +ignorecase: false +nonword: false +action: + name: replace +swap: + Hashicorp: HashiCorp + HASHICORP: HashiCorp diff --git a/docs/.style/styles/Coder/README.md b/docs/.style/styles/Coder/README.md index 2a70166eeb7b1..8602a8330f24e 100644 --- a/docs/.style/styles/Coder/README.md +++ b/docs/.style/styles/Coder/README.md @@ -1,15 +1,15 @@ # Coder custom Vale rules -Custom Vale rules specific to Coder live here. Each rule is a YAML file -that Vale loads through the `BasedOnStyles = Coder` setting in the -repo-root `.vale.ini`. +Custom Vale rules specific to Coder live here. +Each rule is a YAML file that Vale loads through the `BasedOnStyles = Coder` setting in the repo-root `.vale.ini`. -This directory is intentionally empty for now. Follow-up PRs add rules -incrementally. Planned starter rules: +Active rules ship as YAML files in this directory. +See the matching sections in `docs/.style/style-guide.md` for the user-facing policy each rule enforces. +Follow-up PRs add rules incrementally. +Planned coverage: - Dev Container terminology -- HashiCorp casing -- Limit "we" +- Limit `we` - Setup vs set up, Quickstart casing - Next steps vs Learn more - Vale substitution rule scaffold @@ -20,19 +20,15 @@ incrementally. Planned starter rules: ## Authoring a new rule -1. Write a YAML file under this directory. Name it after the rule's - intent, for example `InclusiveLanguage.yml` or `ProductVoice.yml`. -2. Each rule's `message:` should link to the matching section in - `docs/.style/style-guide.md`, ideally with a deep-link anchor, so a - contributor reading a Vale warning can jump straight to the guidance. -3. Land at `level: warning` first. Promote to `level: error` only after - both conditions hold: - - The rule is objectively correct (typo, brand-name casing, banned - substitution). +1. Write a YAML file under this directory. + Name it after the rule's intent, for example `InclusiveLanguage.yml` or `ProductVoice.yml`. +2. Each rule's `message:` should link to the matching section in `docs/.style/style-guide.md`, ideally with a deep-link anchor, so a contributor reading a Vale warning can jump straight to the guidance. +3. Land at `level: warning` first. + Promote to `level: error` only after both conditions hold: + - The rule is objectively correct (typo, brand-name casing, banned substitution). - The existing-content violation count for the rule reaches zero. -4. A follow-up PR will add a parity CI check that verifies every rule - here has a matching section in `style-guide.md`. Add the section in - the same PR as the rule. +4. A follow-up PR adds a parity CI check that verifies every rule here has a matching section in `style-guide.md`. + Add the section in the same PR as the rule. ## Reference diff --git a/docs/admin/integrations/multiple-kube-clusters.md b/docs/admin/integrations/multiple-kube-clusters.md index 4040ec32549e6..32d5ced73bbfc 100644 --- a/docs/admin/integrations/multiple-kube-clusters.md +++ b/docs/admin/integrations/multiple-kube-clusters.md @@ -94,8 +94,7 @@ Alternatively, you can authenticate with remote clusters with ServiceAccount tokens. Coder can store these secrets on your behalf with [managed Terraform variables](../templates/extending-templates/variables.md). -Alternatively, these could also be fetched from Kubernetes secrets or even -[Hashicorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret). +Alternatively, these could also be fetched from Kubernetes secrets or even [HashiCorp Vault](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret). This guide assumes you have a `coder-workspaces` namespace on your remote cluster. Change the namespace accordingly. diff --git a/docs/admin/integrations/opentofu.md b/docs/admin/integrations/opentofu.md index b35f105dd08e8..b078f16af4951 100644 --- a/docs/admin/integrations/opentofu.md +++ b/docs/admin/integrations/opentofu.md @@ -11,8 +11,7 @@ Coder deployments support any custom Terraform binary, including [OpenTofu](https://opentofu.org/docs/) - an open source alternative to Terraform. -You can read more about OpenTofu and Hashicorp's licensing in our -[blog post](https://coder.com/blog/hashicorp-license) on the Terraform licensing changes. +You can read more about OpenTofu and HashiCorp's licensing in our [blog post](https://coder.com/blog/hashicorp-license) on the Terraform licensing changes. ## Using a custom Terraform binary diff --git a/docs/admin/templates/extending-templates/workspace-tags.md b/docs/admin/templates/extending-templates/workspace-tags.md index 3511601761b6a..f2c5ac874cbe1 100644 --- a/docs/admin/templates/extending-templates/workspace-tags.md +++ b/docs/admin/templates/extending-templates/workspace-tags.md @@ -106,13 +106,9 @@ Passing template tags in from other data sources or resources is not permitted. ### HCL syntax -When importing the template version with `coder_workspace_tags`, the Coder -provisioner server extracts raw partial queries for each workspace tag and -stores them in the database. During workspace build time, the Coder server uses -the [Hashicorp HCL library](https://github.com/hashicorp/hcl) to evaluate these -raw queries on-the-fly without processing the entire Terraform template. This -evaluation is simpler but also limited in terms of available functions, -variables, and references to other resources. +When importing the template version with `coder_workspace_tags`, the Coder provisioner server extracts raw partial queries for each workspace tag and stores them in the database. +During workspace build time, the Coder server uses the [HashiCorp HCL library](https://github.com/hashicorp/hcl) to evaluate these raw queries on-the-fly without processing the entire Terraform template. +This evaluation is simpler but also limited in terms of available functions, variables, and references to other resources. #### Supported syntax diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index 138bfdbb98dce..20c47f88a15d4 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.md @@ -10,13 +10,9 @@ underlying infrastructure that all Coder workspaces run on. ## Learn the concepts -While templates are written in standard Terraform, it's important to learn the -Coder-specific concepts behind templates. The best way to learn the concepts is -by -[creating a basic template from scratch](../../tutorials/template-from-scratch.md). -If you are unfamiliar with Terraform, see -[Hashicorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for -common cloud providers. +While templates are written in standard Terraform, it's important to learn the Coder-specific concepts behind templates. +The best way to learn the concepts is by [creating a basic template from scratch](../../tutorials/template-from-scratch.md). +If you are unfamiliar with Terraform, see [HashiCorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for common cloud providers. ## Starter templates diff --git a/docs/manifest.json b/docs/manifest.json index 8504b4fa1074a..4b2c24bc7c8f8 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -808,8 +808,8 @@ "path": "./admin/integrations/dx-data-cloud.md" }, { - "title": "Hashicorp Vault", - "description": "Integrate Coder with Hashicorp Vault", + "title": "HashiCorp Vault", + "description": "Integrate Coder with HashiCorp Vault", "path": "./admin/integrations/vault.md" }, { diff --git a/docs/tutorials/template-from-scratch.md b/docs/tutorials/template-from-scratch.md index 3abfdbf940c10..11ab141ff6e73 100644 --- a/docs/tutorials/template-from-scratch.md +++ b/docs/tutorials/template-from-scratch.md @@ -22,8 +22,8 @@ server essentially runs a `terraform apply` every time a workspace is created, started, or stopped. > [!TIP] -> Haven't written Terraform before? Check out Hashicorp's -> [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials). +> Haven't written Terraform before? +> Check out HashiCorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials). Here's a simplified diagram that shows the main parts of the template we'll create: