mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: add style-guide rule against "whose" for non-person antecedents (#27866)
## What Adds a Word choice entry to the docs style guide, **"Whose for people, not things"**. It restricts "whose" to people and points writers to "with", "where", or "that has" for inanimate objects and abstract concepts, since "whose" implies personhood. ## Where `docs/.style/style-guide/word-choice.md`, inserted right after **Phrasal verbs and their noun forms**, the closest existing grammar/usage rule. Formatting matches the surrounding entries: sentence-case H2, a two-sentence rationale (one sentence per line), `**Do**` / `**Don't**` blockquotes, and a documentation-only enforcement note. ## Rule > "Whose" is the possessive of "who", so it implies the antecedent is a person. > When the antecedent is an inanimate object or an abstract concept, prefer "with", "where", or "that has". Example: - Don't: A chat whose gateway records have been pruned reports no cost. - Do: A chat with pruned gateway records reports no cost. ## Notes - Docs-only change (Markdown under `docs/`, no CI or build config), so it's out of scope for `/coder-agents-review`; the doc-check agent covers docs-only PRs. - The style-guide subpages are Vale-exempt, so no Vale rule ships with this. The enforcement note reads "Documentation-only. No Vale rule.", matching the other documentation-only entries. Linear: [DOCS-612](https://linear.app/codercom/issue/DOCS-612/style-guide-avoid-whose-for-non-person-antecedents) > This PR was created with AI assistance (Coder Agents).
This commit is contained in:
@@ -150,6 +150,30 @@ Treat them consistently across the docs.
|
||||
|
||||
*Enforced by `Coder.PhrasalVerbs` (planned).*
|
||||
|
||||
## Whose for people, not things
|
||||
|
||||
"Whose" is the possessive of "who", so it implies the antecedent is a person.
|
||||
When the antecedent is an inanimate object or an abstract concept, prefer "with", "where", or "that has".
|
||||
|
||||
**Do**:
|
||||
|
||||
> A chat with pruned gateway records reports no cost.
|
||||
>
|
||||
> A template that has conflicting variables fails validation.
|
||||
>
|
||||
> A region where every proxy is unhealthy drops workspace connections.
|
||||
|
||||
**Don't**:
|
||||
|
||||
> A chat whose gateway records have been pruned reports no cost.
|
||||
>
|
||||
> A template whose variables conflict fails validation.
|
||||
>
|
||||
> A region whose proxies are all unhealthy drops workspace connections.
|
||||
|
||||
*Documentation-only.
|
||||
No Vale rule.*
|
||||
|
||||
## Refer to, check out, visit, not see
|
||||
|
||||
When the prose points the reader at another page, section, or external resource, choose the verb that matches the register:
|
||||
|
||||
Reference in New Issue
Block a user