Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
62 lines
3.9 KiB
Markdown
62 lines
3.9 KiB
Markdown
# Documentation Guidelines
|
|
|
|
Read the [style guide](.style/style-guide/README.md) before you write docs prose.
|
|
It is the canonical source; this page is the short list of rules that get missed most often.
|
|
|
|
The surrounding page is not a reliable guide to house style.
|
|
Most of the corpus predates these rules, so match the rules, not the neighbouring lines.
|
|
|
|
When the style guide and the [content guidelines](.style/content-guidelines.md) conflict, the content guidelines govern scope and routing.
|
|
|
|
## Docs contract
|
|
|
|
- **DOC1:** One sentence per source line.
|
|
Don't split a sentence across lines, and don't wrap to a fixed column width.
|
|
`MD013` is disabled on purpose.
|
|
- **DOC2:** Headings are sentence case, don't lead with an `-ing` word, and carry no trailing punctuation.
|
|
- **DOC3:** No em-dashes, en-dashes, or ` -- ` as punctuation, in prose, code, comments, or strings.
|
|
Use commas, semicolons, periods, or a restructured sentence.
|
|
- **DOC4:** Address the reader as "you".
|
|
No first-person singular.
|
|
Reserve "we" for Coder Technologies as a company.
|
|
- **DOC5:** Active voice, present tense, contractions by default.
|
|
Keep sentences short.
|
|
- **DOC6:** Use the canonical term: `select` not `click`, `stop` not `kill`, `turn off` not `disable`, `refer to` or `visit` not `see`, `Learn more` not `Next steps`, `tutorial` not `walkthrough`.
|
|
- **DOC7:** Use canonical product and brand casing, and one term per concept.
|
|
- **DOC8:** One instruction per step.
|
|
Put the condition before the instruction.
|
|
Callouts inform, steps instruct, and a warning states its consequence.
|
|
- **DOC9:** Link text and alt text describe the destination or the image.
|
|
Never `here` or `click here`.
|
|
- **DOC10:** One audience and one outcome per page, declared up front.
|
|
- **DOC11:** Digits for 6 and higher, a non-breaking space between a number and its unit, and the documented date and time formats.
|
|
|
|
## Commands
|
|
|
|
| Task | Command |
|
|
|-------------------|------------------------|
|
|
| Prose lint (Vale) | `make lint/prose` |
|
|
| Markdown lint | `pnpm run check-docs` |
|
|
| Markdown fix | `pnpm run lint-docs` |
|
|
| Table format | `pnpm run format-docs` |
|
|
|
|
Prettier does not own Markdown in this repository.
|
|
Don't run it over `docs/`.
|
|
|
|
## Where the rules live
|
|
|
|
| Topic | Page |
|
|
|----------------------------------------------|-------------------------------------------------------------------------------------------|
|
|
| Line breaks, text formatting, block elements | [formatting.md](.style/style-guide/formatting.md) |
|
|
| Headings, dashes, commas, quotes | [capitalization-and-punctuation.md](.style/style-guide/capitalization-and-punctuation.md) |
|
|
| Person, voice, tense, sentence length | [voice-and-tone.md](.style/style-guide/voice-and-tone.md) |
|
|
| Terminology and banned words | [word-choice.md](.style/style-guide/word-choice.md) |
|
|
| Steps, conditions, callouts | [procedural-writing.md](.style/style-guide/procedural-writing.md) |
|
|
| Link text, alt text, plain English | [accessibility-and-inclusion.md](.style/style-guide/accessibility-and-inclusion.md) |
|
|
| Audience, scope, personas | [audience-and-scope.md](.style/style-guide/audience-and-scope.md) |
|
|
| Numbers, units, dates | [numbers-units-and-dates.md](.style/style-guide/numbers-units-and-dates.md) |
|
|
| What belongs in `docs/` at all | [content-guidelines.md](.style/content-guidelines.md) |
|
|
|
|
Vale enforces a subset of these rules and reports the rest as advisory annotations.
|
|
A clean `make lint/prose` run does not mean the prose follows the style guide.
|