Files
coder/docs/AGENTS.md
T
blinkagent[bot]andblink-so[bot] fb71beee01 docs: add a nested AGENTS.md for docs prose (#28780)
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
2026-08-31 22:44:05 +05:00

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.