Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 17 additions & 16 deletions docs/.style/style-guide/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,25 +23,26 @@ The doctrine for adding Vale rules lives in the [Vale doctrine README](../README

A clean `make lint/prose` run is not evidence that a page follows this guide.
The guide documents 88 rules.
Automated tooling checks 11 of them, and 1 of those 11 doesn't run on published pages.
The other 77 are yours to apply by reading, 78 on published pages, where the one-sentence-per-line rule is off.
Automated tooling checks 12 of them, and 1 of those 12 doesn't run on published pages.
The other 76 are yours to apply by reading, 77 on published pages, where the one-sentence-per-line rule is off.

Open the section that matches what you're writing and work through it.
The linters catch a narrow band of mechanical errors; they can't tell you that a page serves 2 audiences, buries a required step in a `NOTE`, or wraps every paragraph at 80 columns.

### Checks that run today

| Check | Tool | Severity | Scope | What it catches |
|------------------------------------|---------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `Coder.BrandNames` | Vale | `error` | `docs/**` except `docs/.style/style-guide/**` | `Hashicorp` casing only, not the other brands in the word-choice list |
| `Coder.GerundHeading` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | Headings that lead with a gerund |
| `Coder.SelectClick` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | `click` and its inflections |
| `Coder.OneSentencePerLine` | Vale | `warning` | `docs/.style/*.md` and `docs/.style/styles/Coder/*.md` only | Sentence boundaries mid-line, on contributor docs only |
| `Coder.UnitSpacing` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` and `docs/admin/integrations/prometheus.md` and `docs/admin/setup/configuration-reference.md` and `docs/reference/{api,cli}/*.md` | A regular space, or no space, between a number and its unit |
| `MD001`, `MD025`, `MD040`, `MD045` | markdownlint | `error` | All Markdown | Heading increments, single H1, fence language, missing alt text |
| `scripts/check_emdash.sh` | `make lint/emdash` | `error` | Repository | Em-dash, en-dash, and ` -- ` as punctuation |
| `empty-table-header` | `make lint/docs-html` | `error` | `docs/**`, including generated pages | Table header cells with no text, in Markdown and HTML tables |
| `scripts/docsmanifestgen` | `make lint/docs-manifest` | `error` | Descriptions in `docs/manifest/**` and in the front matter of every page they list | A page description that doesn't end with a period |
| Check | Tool | Severity | Scope | What it catches |
|------------------------------------|---------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| `Coder.BrandNames` | Vale | `error` | `docs/**` except `docs/.style/style-guide/**` | `Hashicorp` casing only, not the other brands in the word-choice list |
| `Coder.GerundHeading` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | Headings that lead with a gerund |
| `Coder.LGBTQ` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | Outdated LGBTQ terms, such as `preferred pronouns` and `transgendered` |
| `Coder.SelectClick` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | `click` and its inflections |
| `Coder.OneSentencePerLine` | Vale | `warning` | `docs/.style/*.md` and `docs/.style/styles/Coder/*.md` only | Sentence boundaries mid-line, on contributor docs only |
| `Coder.UnitSpacing` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` and `docs/admin/integrations/prometheus.md` and `docs/admin/setup/configuration-reference.md` and `docs/reference/{api,cli}/*.md` | A regular space, or no space, between a number and its unit |
| `MD001`, `MD025`, `MD040`, `MD045` | markdownlint | `error` | All Markdown | Heading increments, single H1, fence language, missing alt text |
| `scripts/check_emdash.sh` | `make lint/emdash` | `error` | Repository | Em-dash, en-dash, and ` -- ` as punctuation |
| `empty-table-header` | `make lint/docs-html` | `error` | `docs/**`, including generated pages | Table header cells with no text, in Markdown and HTML tables |
| `scripts/docsmanifestgen` | `make lint/docs-manifest` | `error` | Descriptions in `docs/manifest/**` and in the front matter of every page they list | A page description that doesn't end with a period |

The markdownlint row lists only the rules that map to a rule in this guide.
markdownlint runs its full default set minus the rules `.markdownlint.jsonc` disables, so it catches more than these 4.
Expand All @@ -59,11 +60,11 @@ The markdownlint, emdash, docs HTML, and docs-manifest checks do fail the build.
| [Voice and tone](./voice-and-tone.md) | 12 | 0 | 4 | 8 |
| [Procedural writing](./procedural-writing.md) | 6 | 0 | 1 | 5 |
| [Word choice](./word-choice.md) | 20 | 2 | 12 | 6 |
| [Accessibility and inclusion](./accessibility-and-inclusion.md) | 14 | 3 | 5 | 6 |
| [Accessibility and inclusion](./accessibility-and-inclusion.md) | 14 | 4 | 4 | 6 |
| [Capitalization and punctuation](./capitalization-and-punctuation.md) | 12 | 2 | 8 | 2 |
| [Formatting](./formatting.md) | 13 | 3 | 0 | 10 |
| [Numbers, units, and dates](./numbers-units-and-dates.md) | 5 | 1 | 4 | 0 |
| **Total** | 88 | 11 | 34 | 43 |
| **Total** | 88 | 12 | 33 | 43 |

Every column counts rule sections, not linter rule names.
A rule section is a heading that carries an enforcement footer, the italic line that names the section's enforcement status.
Expand All @@ -90,7 +91,7 @@ Classify a counted section from its footer, in this order:
A section that names several checks still counts once.
3. Anything else: the section is planned.

So the 9 rows in the table above name 12 checks, because the markdownlint row bundles 4, and those 12 checks cover 11 sections: each check counts under the section that owns it rather than under every section that mentions it.
So the 10 rows in the table above name 13 checks, because the markdownlint row bundles 4, and those 13 checks cover 12 sections: each check counts under the section that owns it rather than under every section that mentions it.

A rule marked `(planned)` in a section footer names the rule that would enforce it if it existed.
It isn't running today.
Expand Down
3 changes: 2 additions & 1 deletion docs/.style/style-guide/accessibility-and-inclusion.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,8 @@ The Coder docs rarely need these terms, but sample data, persona examples, and f

> The form has an optional field for the user's preferred gender pronouns.

*Enforced by `Coder.LGBTQ` (planned), adapted from the curated alex lexicon.*
*Enforced by `Coder.LGBTQ` (`warning`), adapted from the curated alex lexicon.
The rule flags `a transgender` only when a verb or conjunction follows it, so `a transgender person` stays clean.*

## Descriptive link text

Expand Down
79 changes: 79 additions & 0 deletions docs/.style/styles/Coder/LGBTQ.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Coder.LGBTQ - flag outdated or offensive terms for sex, gender, and sexual
# orientation, and suggest current terms. Refer to
# accessibility-and-inclusion.md#inclusive-lgbtq-terms for the policy.
#
# Adapted from the LGBTQ list in the alex Vale package
# (https://github.com/errata-ai/alex, file alex/LGBTQ.yml), which is released
# under the MIT License, Copyright (c) 2020 errata.ai. The upstream license
# text is available at https://github.com/errata-ai/alex/blob/master/LICENSE.
#
# Changes from upstream:
# - Dropped `bi`. It flags "Power BI" and other uses of "BI" as an initialism.
# - Dropped `special rights`. Permissions docs can use it as a plain technical
# phrase, so it is a likely false positive.
# - Dropped `homo`. It flags "Homo sapiens" and the Latin prefix.
# - Added `a transgender`, used as a noun, which the style guide lists. The key
# matches only when a verb or conjunction follows, so "a transgender person"
# and "a transgender woman" stay clean. A noun use followed by punctuation,
# as in "Ask a transgender.", isn't caught.
# - Replaced the upstream `|` suggestion separator with ", ".
# - Added the message, link, and level fields for Coder.
#
# Vale skips code spans and fenced code blocks, so literal identifiers stay
# untouched when they sit in code font.
#
# Level: warning. Some terms have legitimate quoted or historical uses, so the
# fix is a judgment call.
extends: substitution
message: "Use '%s' instead of '%s'. Refer to accessibility-and-inclusion.md#inclusive-lgbtq-terms."
link: https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#inclusive-lgbtq-terms
level: warning
ignorecase: true
action:
name: replace
swap:
bathroom bill: non-discrimination law, non-discrimination ordinance
biologically female: assigned female at birth, designated female at birth
biologically male: assigned male at birth, designated male at birth
born a man: assigned male at birth, designated male at birth
born a woman: assigned female at birth, designated female at birth
dyke: gay
fag: gay
faggot: gay
gay agenda: gay issues
gay lifestyle: gay lives, gay/lesbian lives
gay rights: equal rights, civil rights for gay people
gender pronoun: pronoun, pronouns
gender pronouns: pronoun, pronouns
genetically female: assigned female at birth, designated female at birth
genetically male: assigned male at birth, designated male at birth
hermaphrodite: person who is intersex, person, intersex person
hermaphroditic: intersex
heshe: transgender person, person
homosexual: gay, gay man, lesbian, gay person/people
homosexual agenda: gay issues
homosexual couple: couple
homosexual lifestyle: gay lives, gay/lesbian lives
homosexual marriage: gay marriage, same-sex marriage
homosexual relations: relationship
homosexual relationship: relationship
preferred pronoun: pronoun, pronouns
preferred pronouns: pronoun, pronouns
pseudo hermaphrodite: person who is intersex, person, intersex person
pseudo hermaphroditic: intersex
pseudohermaphrodite: person who is intersex, person, intersex person
pseudohermaphroditic: intersex
sex change: transition, gender confirmation surgery
sex change operation: sex reassignment surgery, gender confirmation surgery
sexchange: transition, gender confirmation surgery
sexual preference: sexual orientation, orientation
she male: transgender person, person
shehe: transgender person, person
shemale: transgender person, person
sodomite: gay
tranny: transgender
transgendered: transgender
transgenderism: being transgender, the movement for transgender equality
transgenders: transgender people
transvestite: cross-dresser
'a transgender (?:is|was|who|and|or|but|that|has|had|can|will|would|should)': transgender person
Loading