docs/AGENTS.md
Rama main · réplica de lectura del repositorio original.
# 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 neighboring 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.
Do not split a sentence across lines, and do not 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, parentheses, periods, or a restructured sentence, not semicolons.
- **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.
Spell out negative instructions: `do not`, not `don't`.
Keep sentences short, and keep each step to 20 words or fewer.
- **DOC6:** Use the canonical term: `select` not `click`, `stop` not `kill`, `turn off` not `disable`, `refer to` or `visit` not `see` or `check out`, `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.
Do not 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.