## Summary A feature `state` in `docs/manifest/` now applies to a route and all its descendants, so each state is set once on the highest route it applies to. `docsmanifestgen check` rejects a route that repeats an ancestor's state, and the repeated states on `main` are removed. ## State model - Put a state on the highest route it applies to. - Add a state to a descendant only when it is new, such as an early access page inside a Premium section. - The sidebar shows a pill on the route that sets the state and on descendants whose state differs. - Every page shows its full state, own plus inherited, under the title. ## Changes - `docsmanifestgen check` (`make lint/docs-manifest`) fails when a route repeats an ancestor's state, following include files and overlays, or lists a state twice. It runs only after the manifest builds cleanly. Table-driven tests in `scripts/docsmanifestgen/state_test.go`. - Keep `state: [premium]` on AI Governance and External provisioners only. Remove the 27 states their descendants repeat in `docs/manifest/ai-governance/**` and `docs/manifest/install/operate/provisioners.yml`, and regenerate `docs/manifest.json`. - Document the model in `contributing/documentation.md` (new "Feature states" section with a YAML example), `docs/.style/content-guidelines.md`, and the doc-check skill. > [!IMPORTANT] > Inherited pills under the page title and the new sidebar behavior need the matching docs-engine change ([DOCS-1440](https://linear.app/codercom/issue/DOCS-1440)). > Merge this after that ships, or child pages show no state pill until it does. ## Testing - `go test ./scripts/docsmanifestgen/... ./scripts/docgenenv/...` - `golangci-lint run ./scripts/docsmanifestgen/...` - `GOOS=windows` and `GOOS=darwin` `go vet ./scripts/docsmanifestgen/` - `make lint/docs-manifest`, `make lint/markdown`, `make lint/docs-redirects` - `make gen/docs-manifest` leaves the tree clean. <details> <summary>Decision log: rebase onto main after #31645</summary> - #31645 (merged 2026-11-04) moved AI Governance to a top-level section with Agent Firewall and AI Gateway nested under it, and added the `ai-coder/...` redirects. That covered this PR's move commits, link and URL updates, and redirects, which caused the conflicts. - The branch was rebuilt on `main`: the two move commits were dropped, and the four state-tooling and guidance commits were cherry-picked. The manifest cleanup was redone as a new commit against `main`'s layout, using the new lint's output as the list of repeated states. - Agent Relay is now top-level with `state: [premium, beta]` and no child states, so it needs no change. - Conflicts in `content-guidelines.md` and the doc-check skill were resolved to keep `main`'s newer text (Vale word-choice updates and relative redirect syntax) and apply only the feature-states lines. - The pre-rebase head was `a797f59737`. </details> > Generated by Coder Agents on behalf of @nickvigilante. Supersedes #31481, reopened under a human author for attribution. --------- Co-authored-by: default <default@example.com>
8.9 KiB
Documentation
This style guide is primarily for use with authoring documentation.
General guidelines
- Use sentence case, even in titles (do not punctuate the title, though)
- Use the second person
- Use the active voice
- Use plural nouns and pronouns (they, their, or them), especially when the specific number is uncertain (i.e., "Set up your environments" even though you don't know if the user will have one or many environments)
- When writing documentation titles, use the noun form, not the gerund form (e.g., "Environment Management" instead of "Managing Environments")
- Context matters when you decide whether to capitalize something or not. For example, "A Job creates one or more Pods..." is correct when writing about Kubernetes. However, in other contexts, neither job nor pods would be capitalized. Please follow the conventions set forth by the relevant companies and open source communities.
Third-party references
If you have questions that aren't explicitly covered by this guide, consult the following third-party references:
| Type of guidance | Third-party reference |
|---|---|
| Spelling | Merriam-Webster.com |
| Style - nontechnical | The Chicago Manual of Style |
| Style - technical | Microsoft Writing Style Guide |
Tools
This repository runs Vale on docs/ as part of CI.
The configuration is the repo-root .vale.ini, and the curated rule set is documented in docs/.style/style-guide/.
Run the same checks locally with make lint/prose.
Vale checks a small subset of the style guide, and it runs in advisory mode: warnings surface as inline PR annotations, but they don't block the build. A clean Vale run doesn't mean a page follows the guide. Refer to What the tooling checks, and what it doesn't for the current coverage, then apply the guide yourself.
The following external tools can also help when drafting. Take their suggestions with a grain of salt because they aren't tuned for Coder's voice or product names:
Feature states
A feature state, such as premium, beta, or early access, marks a page in the sidebar and under the page title.
Set it with the state key on the page's route in the YAML sidebar sources under docs/manifest/, not in the page title or H1.
A state on a route applies to that route and to every route beneath it. Follow these rules:
- Put the state on the highest route it applies to.
For a Premium feature with several pages, set
state: [premium]on the feature's top-level route only. - Do not repeat an ancestor's state on a descendant. The descendant inherits it.
- Add a state to a descendant only when the descendant has a state that its ancestors lack, such as an early access subfeature inside a Premium feature. List only the new state; the inherited one still applies.
make lint/docs-manifest fails when a route repeats a state that an ancestor already sets, and names the file, the route, and the ancestor.
Include files count: an ancestor in another file still counts as an ancestor.
The lint also fails when a route lists the same state twice.
Example
A Premium feature with an early access subfeature:
# docs/manifest/admin/widgets.yml
title: Widgets
description: Manage widgets across your deployment.
path: ./admin/widgets/index.md
state: [premium]
children:
- title: Widget setup
description: Enable and configure widgets.
path: ./admin/widgets/setup.md
- title: Widget sync
description: Sync widgets between deployments.
path: ./admin/widgets/sync.md
state: [early access]
Widget setup sets no state and inherits Premium.
Widget sync sets only early access and inherits Premium as well.
Do not write state: [premium, early access] on Widget sync, because the lint rejects the repeated premium.
The docs site shows each page as follows:
| Route | Own state |
Sidebar pill | Pills under the page title |
|---|---|---|---|
Widgets |
[premium] |
Premium | Premium |
Widget setup |
none | none | Premium |
Widget sync |
[early access] |
Early access | Premium, Early access |
The sidebar shows a pill on the route that sets a state and on any descendant whose state differs, so a section reads as Premium once instead of on every entry. The pills under a page title show the page's full state: its own states plus every state it inherits.
Inherited pills under the page title require the docs-engine change that adds state inheritance. Until the docs site runs that version, a page shows only the states set on its own route.
Refer to the feature states rule in the content guidelines for the canonical rule.
How to format text
Below summarizes the text-formatting conventions you should follow.
Bold
Use bold formatting when referring to UI elements.
Italics
Use italics for:
- Parameter names
- Mathematical and version variables
Code font
Use code font for:
- User text input
- Command-line utility names
- DNS record types
- Environment variable names (e.g.,
PATH) - Filenames, filename extensions, and paths
- Folders and directories
- HTTP verbs, status codes, and content-type values
- Placeholder variables (see Placeholders in angle brackets)
Use code blocks for code samples and other blocks of code. Be sure to indicate the language your using to apply the proper syntax highlighting.
This is a codeblock.
For code that you want users to enter via a command-line interface, use
console, not bash.
Placeholders in angle brackets
Placeholder values written in angle brackets must be wrapped in backticks so
they render as inline code. The documentation site renders Markdown as HTML, so
an unwrapped placeholder such as <organization-name> is parsed as an unknown
HTML tag and stripped out of the page, so readers never see it.
This applies wherever the text becomes documentation, including the Go CLI help strings and Swagger annotations that generate the CLI and API reference.
# Correct: wrap the placeholder in backticks
Structured as: `<organization-name>/<team-slug>`.
# Incorrect: the placeholder renders as "Structured as: /."
Structured as: <organization-name>/<team-slug>.
Punctuation
Do not use the ampersand (&) as a shorthand for and unless you're referring to a UI element or the name of something that uses &.
You can use the symbol ~ in place of the word approximately.
UI elements
When referring to UI elements, including the names for buttons, menus, dialogs, and anything that has a name visible to the user, use bold font.
Example: On the Environment Overview page, select Configure SSH.
Don't use code font for UI elements unless it is rendered based on previously
entered text. For example, if you tell the user to provide the environment name
as myEnvironment, then use both bold and cold font when referring to the name.
Example: Select myEnvironment.
When writing out instructions that involve UI elements, both of the following options are acceptable:
- Go to Manage > Users.
- In the Manage menu, select Users.
Product-specific references
Below summarizes the guidelines regarding how Coder terms should be used.
Capitalized terms
The only Coder-specific terms that should be capitalized are the names of products (e.g., Coder).
The exception is code-server, which is always lowercase. If it appears at the beginning of the sentence, rewrite the sentence to avoid this usage.
Uncapitalized terms
In general, we do not capitalize the names of features (unless the situation calls for it, such as the word appearing at the beginning of a sentence):
- account dormancy
- audit logs
- autostart
- command-line interface
- dev URLs
- environment
- image
- metrics
- organizations
- progressive web app
- registries
- single sign-on
- telemetry
- workspace
- workspace providers
- workspaces as code
We also do not capitalize the names of user roles:
- auditor
- member
- site admin
- site manager
Standardized spellings
- WiFi