AI Rules for Documentation Style

README Documentation Standards

README structure rules: AI rule: 'Every project README follows this structure: 1) Project name and one-sentence description. 2) Quick start (3 commands to get running). 3) Prerequisites (required tools and versions). 4) Installation (step-by-step setup). 5) Usage (common operations with examples). 6) Configuration (environment variables and options). 7) Testing (how to run tests). 8) Deployment (how to deploy). 9) Contributing (how to contribute). No sections beyond these unless the project has unique requirements.' The AI: generates READMEs with a consistent, complete structure. The developer: finds any information in a predictable location.

README content rules: AI rule: 'Quick start must work. Every command in the README: tested and verified. No placeholder values without clear indication (use YOUR_API_KEY not actual keys). Code examples: complete and runnable (not snippets that require missing context). Version numbers: specific (Node.js 20.x, not Node.js). Links: to specific documentation pages, not to root domains.' The AI: generates README content that a developer can follow without guessing. The README: a working guide, not a marketing document.

README maintenance rules: AI rule: 'Update the README when: adding a new environment variable, changing the installation process, modifying the build command, or adding a new dependency that requires setup. The README: a living document that stays synchronized with the project. A stale README with wrong installation steps: worse than no README (because the developer follows the steps, fails, and wastes time debugging the documentation instead of the code).' AI rule: 'README rules ensure that AI-generated documentation is useful from day one. The structure: predictable. The content: verified. The maintenance: tied to code changes. A good README: the first thing a new developer reads and the last thing that should be wrong.'

API Documentation Standards

API endpoint documentation: AI rule: 'Every API endpoint documented with: HTTP method and path, description (one sentence), request body schema (with types and required/optional), response schema (with types and example), error responses (status codes and error body), authentication requirements (public, authenticated, admin), and rate limits (if applicable). Format: OpenAPI/Swagger spec generated from code annotations, not maintained separately.' The AI: generates API documentation alongside the endpoint code. The documentation: always in sync because it is generated from the source.

API documentation examples: AI rule: 'Every endpoint includes a curl example showing a complete request and response. The example: uses realistic data (not foo/bar). The request: includes all required headers (Authorization, Content-Type). The response: shows the actual response shape with realistic values. The example: copy-pasteable (a developer can run the curl command and get the documented response from the development server).' The AI: generates practical, testable API examples. The developer using the API: can verify their integration by comparing with the documented example.

API changelog documentation: AI rule: 'API changes documented in CHANGELOG.md or API-CHANGELOG.md. Format: date, version, list of changes. Breaking changes: highlighted with BREAKING prefix and migration instructions. New endpoints: listed with brief description and link to full documentation. Deprecated endpoints: listed with deprecation date and replacement endpoint. The changelog: generated from conventional commits (feat and fix commits touching api/ directory).' AI rule: 'API documentation rules ensure that developers consuming the API have everything they need: what the endpoint does, how to call it, what it returns, and what changed since they last integrated. The AI generates this documentation alongside the code — never separately, never manually.'

Architecture Documentation Standards

Architecture overview: AI rule: 'The project includes an ARCHITECTURE.md file covering: 1) System overview (one paragraph describing the system and its purpose). 2) Component diagram (showing major components and their relationships). 3) Data flow (how data moves through the system from request to response). 4) Technology choices (what tools/libraries are used and why). 5) Key patterns (architectural patterns used: vertical slices, CQRS, event sourcing, etc.). Update ARCHITECTURE.md when adding a new major component or changing the data flow.' The AI: references ARCHITECTURE.md when generating code to ensure new code fits the architecture.

Decision documentation: AI rule: 'Significant technical decisions documented as Architecture Decision Records (ADRs) in docs/adr/ directory. ADR format: 1) Title (short description of the decision). 2) Status (proposed, accepted, deprecated, superseded). 3) Context (what problem are we solving). 4) Decision (what we decided). 5) Consequences (what happens as a result — both positive and negative). Naming: 0001-use-drizzle-for-database.md, 0002-adopt-result-pattern.md. New ADRs: created when choosing a library, changing architecture, or adopting a new pattern.' The AI: generates ADRs when implementing architectural changes. The team: has a searchable history of why decisions were made.

Module documentation: AI rule: 'Each major module includes a MODULE.md or a detailed JSDoc comment at the top of the entry file. Content: 1) What the module does (one paragraph). 2) Key exports (list of primary functions/classes and their purpose). 3) Dependencies (what other modules this module depends on). 4) Usage example (how to import and use the module). No module documentation for simple, single-file utilities — only for modules with 3+ files or complex internal logic.' AI rule: 'Architecture documentation serves the developer who joins in 6 months and asks: why was this built this way? ADRs answer specific decisions. ARCHITECTURE.md answers the overall design. MODULE.md answers how each piece works. Together: a complete picture that no amount of code reading can provide.'

Documentation Quality and Maintenance

Documentation testing: AI rule: 'All code examples in documentation: tested in CI. Extract code blocks from README and docs, run them as tests. If a code example fails: CI fails. This ensures: installation instructions work, API examples return correct responses, and code snippets compile. Documentation that is not tested: documentation that drifts. Documentation that is tested: documentation that stays current.' The AI: generates testable documentation. The CI: catches stale examples automatically.

Writing style for documentation: AI rule: 'Documentation writing style: 1) Active voice (the function returns, not the result is returned). 2) Present tense (this endpoint creates a user, not this endpoint will create). 3) Second person for tutorials (you can configure, not one can configure). 4) Short sentences (maximum 25 words). 5) One concept per paragraph. 6) Code before explanation (show the example first, then explain it). 7) American English spelling. 8) No jargon without definition.' The AI: generates readable documentation with consistent style.

Documentation review checklist: AI rule: 'Before merging documentation changes: 1) All code examples verified to work. 2) All links tested (no 404s). 3) All version numbers current. 4) No placeholder text remaining. 5) Formatting renders correctly in markdown preview. 6) New content follows the established structure. 7) Changed code: corresponding documentation updated.' The checklist: applied to documentation PRs just like code review checklists are applied to code PRs. AI rule: 'Documentation quality rules treat docs as a first-class engineering artifact. The same rigor applied to code (testing, review, maintenance): applied to documentation. The result: documentation that developers trust because it is as reliable as the code itself.'

Documentation Style Quick Reference

Quick reference for AI coding documentation rules.

• README: 9-section structure, quick start that works, specific versions, runnable code examples
• API docs: endpoint schema + curl examples + error responses — generated from code annotations
• API changelog: conventional commits generate changelog, breaking changes highlighted with migration
• Architecture: ARCHITECTURE.md for overview, docs/adr/ for decisions, MODULE.md for complex modules
• ADR format: title, status, context, decision, consequences — one ADR per significant decision
• Testing: CI extracts and runs code examples from docs — stale examples fail the build
• Writing style: active voice, present tense, short sentences, code before explanation, American English
• Maintenance: documentation updated alongside code changes — never separately, never later