coder/docs/AGENTS.md

Documentation Guidelines

Read the style guide 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 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
Headings, dashes, commas, quotes	capitalization-and-punctuation.md
Person, voice, tense, sentence length	voice-and-tone.md
Terminology and banned words	word-choice.md
Steps, conditions, callouts	procedural-writing.md
Link text, alt text, plain English	accessibility-and-inclusion.md
Audience, scope, personas	audience-and-scope.md
Numbers, units, dates	numbers-units-and-dates.md
What belongs in docs/ at all	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.