## Summary **Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`). Adds a front-matter `title` to every navigable docs page whose title can be migrated **mechanically**, with no editorial judgment. This is the content step that Phase 1 (renderers prefer front-matter title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware, `DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged and live. **Rendered no-op.** The renderers already resolve the page title from the manifest and hide the leading body H1 (Phase 1), so no page changes visually. This just moves the title into front matter where Fumadocs and the migrated tooling can read it. ## What's in this batch Dry-run on `main` (464 navigable pages) splits into: | category | count | this PR | |----------|-------|---------| | already has front-matter title (Reference, from Phase 2 generators) | 196 | skipped (idempotent) | | **mechanical** — leading body H1 equals the manifest label | 138 | ✅ add front-matter `title`, drop the duplicate H1 | | **no body H1** — renders under the manifest label only | 4 | ✅ add front-matter `title` only | | **mismatch** — body H1 differs from the manifest label | 126 | ⏭️ deferred (needs an editorial decision, see below) | 142 files changed, all under `docs/`. ## Deliberately out of scope: the 126 mismatches Pages where the body H1 is richer than the short sidebar label (e.g. label **Modules** / H1 *Contributing modules*, label **Install** / H1 *Installing Coder*) need a canonical-title decision, not a script. A few even look like the body H1 is the redundant one (`install/cli.md` and `install/index.md` both carry the H1 *Installing Coder*). These will land in follow-up batches **by nav section** once the policy is set, so each gets real review. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Every added front-matter block parses as YAML and its `title` round-trips to the manifest label (checked programmatically across all 142 files). - Every removed line is a leading `# H1` that equalled the manifest title; no body prose was reflowed. Front matter is correctly hoisted above pre-existing `<!-- markdownlint-disable -->` comments on the two pages that had them. - `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in Phase 4); `MD025` is not tripped because the duplicate body H1s are removed. ``` $ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main) Linting: 142 file(s) Summary: 0 error(s) ``` Linear: DOCS-484 > This PR was created with AI assistance (Coder Agents).
176 lines
5.8 KiB
Markdown
176 lines
5.8 KiB
Markdown
---
|
|
title: 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..."](https://kubernetes.io/docs/concepts/workloads/controllers/job/)
|
|
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](https://www.merriam-webster.com/) |
|
|
| Style - nontechnical | [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html) |
|
|
| Style - technical | [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) |
|
|
|
|
## Tools
|
|
|
|
This repository runs [Vale](https://vale.sh/) on `docs/` as part of CI to enforce prose style.
|
|
The configuration is the repo-root `.vale.ini`, and the curated rule set is documented in [`docs/.style/style-guide/`](https://github.com/coder/coder/tree/main/docs/.style/style-guide).
|
|
Run the same checks locally with `make lint/prose`.
|
|
Vale runs in advisory mode in this iteration: warnings surface as inline PR annotations, but they don't block the build.
|
|
|
|
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:
|
|
|
|
- [alex.js](https://alexjs.com/)
|
|
- [Grammarly](https://app.grammarly.com/)
|
|
- [Hemingway Editor](https://hemingwayapp.com/)
|
|
|
|
## 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](#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.
|
|
|
|
```txt
|
|
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.
|
|
|
|
```text
|
|
# 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
|