Skip to content

Latest commit

 

History

History
 
 

.style

Folders and files

README.md

docs/.style/

Contributor-facing style and content guidance for the Coder documentation. Nothing under this directory is published to coder.com/docs.

What lives here

Path Purpose
content-guidelines.md Canonical content rules: what belongs in docs/, what doesn't, why
style-guide/ Canonical prose style guide for docs/
styles/Coder/ Custom Vale rules specific to Coder (product voice, terms)

Refer to content-guidelines.md for the canonical rules on what content belongs in docs/ and what to route elsewhere (blog, changelog, Support KB, and so on).

Visit style-guide/ for the prose style guide. The styles/Coder/ directory holds the custom Vale rules that enforce parts of the guide. Vale's StylesPath in the repo-root .vale.ini points at docs/.style/styles/.

Why a hidden directory

The leading dot mirrors the .github/, .vscode/, and .claude/ convention already used in this repo for tooling-internal directories. The structural Markdown linters and Vale still pick it up (except the style guide's own prose under style-guide/, which is exempt). Coder.com's docs site does not. Refer to "What does not run against this directory" below for that exemption.

How exclusion from coder.com works

coder.com/docs routes and search are manifest-driven:

Net result: not adding anything from docs/.style/ to docs/manifest.json gives us no route, no Algolia record, and no sidebar entry. Two defense-in-depth changes in .github/workflows/deploy-docs.yaml keep the deploy workflow from running on .style-only commits and exclude the directory from the surgical-reindex payload on mixed commits.

What still runs against this directory

  • make lint/markdown (markdownlint-cli2) processes every Markdown file here. The repo-root package.json invokes markdownlint-cli2 --fix $(find docs -name '*.md').
  • make fmt/markdown (markdown-table-formatter) reflows tables here for the same reason.
  • Vale (make lint/prose) lints everything here except the style guide's own prose under style-guide/: the landing page, content-guidelines.md, the annotation demo (whose Coder.Demo* rules are meant to fire), and the Coder rule docs. Refer to the repo-root .vale.ini for the active configuration, and to "What does not run against this directory" below for the one exemption.

What does not run against this directory

  • linkspector: excluded via excludedDirs in .github/.linkspector.yml. External-link checking is overkill for contributor tooling.
  • The deploy-docs workflow: its paths: filter negates docs/.style/**, and the surgical-reindex git-diff invocation excludes the same path. See .github/workflows/deploy-docs.yaml.
  • The docs-preview workflow: its paths: filter negates docs/.style/**, so .style-only PRs produce no preview comment. The selection logic also skips .style files when picking the preview target on mixed PRs. See .github/workflows/docs-preview.yaml.
  • Vale's Coder rules on the style guide's own prose under docs/.style/style-guide/. The guide deliberately contains the constructs the rules ban, such as Don't examples and banned terms named in headings and prose, so the repo-root .vale.ini clears BasedOnStyles for docs/.style/style-guide/**. Nothing else under docs/.style/ is exempt: the landing page, content-guidelines.md, the annotation demo, and the Coder rule docs are all linted. Zero-baseline is therefore measured over docs/ excluding docs/.style/style-guide/. The exemption applies only when the path resolves to docs/.style/style-guide/... from the working directory, which is what make lint/prose and continuous integration (CI) pass (repo-root-relative docs/...). Other invocation forms bypass the glob and still flag the guide's intentional examples: absolute paths (what editors and Language Server Protocol (LSP) integrations pass) and subdirectory-relative paths (for example vale .style/style-guide/... run from docs/). Treat those in-editor and subdirectory findings on the guide as expected.

Edit the content guidelines

Open a PR against docs/.style/content-guidelines.md. The rules in that file apply to humans and AI-assisted workflows alike. When it conflicts with another style or contributing doc in the repo, it governs.

Edit the style guide

Open a PR against the appropriate subpage of docs/.style/style-guide/. Follow-up PRs add each rule and the matching style-guide section together.

Reviewer personas in front matter

The doc-check skill reviews docs changes through several personas, each focused on one kind of problem, such as accuracy or word choice. Each rule page lists the personas that apply its rules in a review-personas front matter field:

---
review-personas: [language, consistency, accuracy]
---

The skill finds a persona's rules by reading this field, not by file path, so pages can move or split without breaking the review. When you add a rule page, add the field. When you move a rule to a different page, check that the new page lists every persona that applied it. The persona IDs and what each one reviews are in .claude/skills/doc-check/personas/. The CI review of a PR runs only the accuracy, coverage, and learner personas, so it applies only the rule pages that list one of them. The other personas run when an author uses the skill on their own branch.

Add a Vale rule

Each rule in the repo-root .vale.ini at warning or error severity ships clean: zero baseline findings against the current docs/ corpus, excluding docs/.style/style-guide/, which is exempt because the style guide demonstrates the violations the rules ban. A suggestion rule can ship with existing findings, as the severity notes below describe. The PR that adds a rule is the rule's complete unit:

  1. Cleanup commit: fix every existing-content violation of the new rule so make lint/prose reports zero findings for it.

    The cleanup ships in the same PR as the enable, ordered first. For a suggestion rule, the cleanup is optional.

  2. Enable commit: enable the rule in .vale.ini, document it in the style guide, and add its YAML if applicable.

    Set the rule's chosen severity in .vale.ini. Write a corresponding section under the matching subpage of docs/.style/style-guide/, and add the custom rule YAML under docs/.style/styles/Coder/. The rule's message: field points at the relevant style-guide subpage anchor. Update the coverage tables on style-guide/README.md in the same commit. make lint/style-claims fails when a rule lands without its section, when the tables disagree with .vale.ini, or when an annotation claims enforcement that doesn't exist. Refer to scripts/styleclaims/README.md for the annotation format the checker reads, including how to mark a planned rule.

Severity is a deliberate per-rule choice:

  • error blocks merge. Use for hard policy where any violation is wrong: brand-name casing, first-person pronouns we ban outright, em-dash bans.
  • warning surfaces an annotation without failing CI. Use for strong guidance with legitimate human-judgment exceptions: terms that need context (disabled as a technical state vs. ableist usage), judgment-bound style preferences.
  • suggestion surfaces a notice annotation. Use for soft guidance where the right fix is contextual: noun-as-adjective patterns like desired state, wordiness, optional sentence reshaping.

The severity choice and the cleanup discipline are independent, with one exception. A rule landing at warning or error ships with zero baseline findings. The rule's purpose is to catch new violations, not to surface a backlog of existing ones. A rule that surfaces a standing backlog at those severities teaches contributors to ignore the annotation channel, which erodes trust in CI regardless of the severity at which the noise arrives.

A rule at suggestion severity can land while existing findings remain. A suggestion is a soft nudge that a writer can accept or ignore, so a standing count doesn't mean the docs break a rule. The PR that adds a suggestion rule states its baseline count, and it can fix existing findings in the same PR.

PR title: feat(docs/.style): enable <RuleName>.

False-positive policy: one confirmed false positive after enable, either refine the rule or revert. We do not maintain rules that occasionally cry wolf, regardless of severity.

If a policy is judgment-bound (passive voice, weasel words, sentence-case headings on a corpus with many proper nouns), write a Coder-authored rule with the precision the situation needs instead of accepting an imprecise third-party rule at any severity.

This applies equally to Coder-authored rules (under docs/.style/styles/Coder/) and third-party rules from Google, alex, and write-good. Third-party rules are not loaded by default. Each returns through the same per-rule PR pattern after its corpus is clean.