## Merge order Merge first; then republish the docs; then coder/coder.com#1100 (the redirects). ## Summary The nine pages under `docs/about/contributing/` are for people working in this repository, not for Coder users or administrators, so they leave the published documentation. The repository becomes their canonical home. Until now the root `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` were two-line stubs that only linked to the docs site, so contributors on GitHub were bounced out to read them. A companion PR in `coder/coder.com` adds redirects from every retired `/docs/about/contributing/*` URL to the new GitHub location. It must merge only after this PR has merged and the docs have republished. ## Changes | Old path | New path | | -- | -- | | `docs/about/contributing/CONTRIBUTING.md` | `CONTRIBUTING.md` (replaces the stub) | | `docs/about/contributing/CODE_OF_CONDUCT.md` | `CODE_OF_CONDUCT.md` (replaces the stub) | | `docs/about/contributing/SECURITY.md` | deleted; the root `SECURITY.md` already holds the policy | | `docs/about/contributing/AI_CONTRIBUTING.md` | `contributing/AI_CONTRIBUTING.md` | | `docs/about/contributing/backend.md` | `contributing/backend.md` | | `docs/about/contributing/frontend.md` | `contributing/frontend.md` | | `docs/about/contributing/modules.md` | `contributing/modules.md` | | `docs/about/contributing/templates.md` | `contributing/templates.md` | | `docs/about/contributing/documentation.md` | `contributing/documentation.md` (see note below) | For every moved file: the docs front matter is stripped and its `title` becomes the H1, relative links are rewritten for the new depth (`../../../foo` becomes `./foo` at the root and `../foo` under `contributing/`; the two links into `docs/admin/` become `../docs/admin/...`), and the docs-only `<div class="tabs">` wrapper in `CONTRIBUTING.md` is removed. `CONTRIBUTING.md` gains a short intro that links the code of conduct, the security policy and the area guides, since GitHub only auto-surfaces the root files. `docs/manifest.json` loses the About → Contributing group and `docs/images/icons/contributing.svg`, which only that group used. Inbound references updated: - `README.md`: contribution guide link now points at `CONTRIBUTING.md` on GitHub. - `docs/tutorials/example-guide.md` and `docs/install/releases/feature-stages.md`: link to `contributing/documentation.md` on GitHub, since a docs page cannot link to a repo-only file. - `docs/.style/style-guide/README.md`: the "Relationship to" section names the new location. - `scripts/docshtmlcheck/main.go`: both the package comment and the user-facing error string name `contributing/documentation.md`. - `scripts/docshtmlcheck/README.md`: relative link to the new location. - `coderd/database/migrations/migrate_test.go`: `t.Log` link now points at `contributing/backend.md#database-fixtures-for-testing-migrations`. - `.github/pull_request_template.md`: AI contribution guidelines link. - `.github/workflows/contrib.yaml`: commit-message guidelines link in the PR title check. - `.github/workflows/test-docs-preview-mapper.sh`: the mapper test case that used `docs/about/contributing/CONTRIBUTING.md` now uses `docs/admin/security/audit-logs.md`. - `.claude/docs/{ARCHITECTURE,PR_STYLE_GUIDE,WORKFLOWS,DOCS_STYLE_GUIDE}.md`: links to `CONTRIBUTING.md`. `git grep about/contributing` is empty after this change. `CODEOWNERS` had no entry for the old paths. Note on `documentation.md`: it is docs-authoring guidance and is parked in `contributing/` for now. Folding it into `docs/.style/` is tracked separately and is deliberately not attempted here. ## Testing - `go run ./scripts/docshtmlcheck` over `docs/`, and again over `contributing/`, `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`: clean. - `go vet ./scripts/docshtmlcheck/...` and `go test ./scripts/docshtmlcheck/...`: 47 tests pass. - `go vet ./coderd/database/migrations/...`: clean. `go test` for that package fails to link on this machine (`tailscale.com/tstime/mono: invalid reference to runtime.nanotime1`) identically on unmodified `main`, so it is a local toolchain issue and not exercised here; the change is a string in a `t.Log`. - `pnpm check-docs` (markdownlint-cli2 and markdown-table-formatter over `docs/`, `.claude/docs/`, root `*.md`): 495 files, 0 errors. The same two tools over `contributing/*.md`: 0 errors. - Every relative link in the eight moved files resolves to an existing path (scripted check). - `bash .github/workflows/test-docs-preview-mapper.sh`: the changed `assert_maps_to` case passes; the six `resolve_ref`/`pages_for_image` failures it reports are identical on unmodified `main` on macOS. Linear: [DOCS-975](https://linear.app/codercom/issue/DOCS-975) --- 🤖 Built with AI assistance.
177 lines
6.1 KiB
Markdown
177 lines
6.1 KiB
Markdown
# 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.
|
|
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 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](https://github.com/coder/coder/blob/main/docs/.style/style-guide/README.md#what-the-tooling-checks-and-what-it-doesnt) 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:
|
|
|
|
- [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
|