AI Rules for Documentation and Markdown

Why Documentation Rules Matter for AI

AI assistants generate documentation that's technically accurate but stylistically chaotic. One README uses h2 for section headers, another uses h3. API docs sometimes include request examples, sometimes don't. Inline code comments alternate between verbose explanations and cryptic abbreviations. The result is documentation that reads like it was written by 10 different people — because it effectively was.

Documentation rules are uniquely high-leverage for AI because docs are generated frequently: README files, inline comments, API reference docs, PR descriptions, commit messages. Every one of these benefits from consistent formatting, tone, and structure.

These rules cover four documentation contexts: README files, API documentation, inline code comments, and technical writing style. Pick the sections that apply to your project.

Rule 1: README Structure and Content

The rule: 'Every README follows this structure: Project Name (h1), one-sentence description, badges (build, coverage, version), Getting Started (h2) with prerequisites and installation, Usage (h2) with primary use case example, API/Configuration (h2) if applicable, Contributing (h2) with link to CONTRIBUTING.md, and License (h2). No section is optional — if it doesn't apply, omit the heading, don't leave an empty section.'

For the description: 'The first line after the h1 is a single sentence that explains what the project does and for whom. Not how it works, not the tech stack, not the history — just what it does. Example: "A CLI tool that syncs AI coding rules across multiple repositories." This line appears in GitHub search results and package registries.'

For code examples: 'The Getting Started section must include a working example that a new user can copy-paste and run. Not a theoretical example, not a partial snippet — a complete, runnable example. Use bash code blocks for terminal commands, language-specific code blocks for code.'

• h1: Project Name — one-sentence description immediately after
• Badges: build status, coverage, latest version, license
• Getting Started: prerequisites + installation + first use (copy-pasteable)
• Usage: primary use case with complete, runnable code example
• Contributing: link to CONTRIBUTING.md, not inline instructions
• License: name and link — one line, not the full license text

Rule 2: API Documentation Conventions

The rule: 'Every public API endpoint or function has documentation that includes: description (one sentence, what it does), parameters (name, type, required/optional, description), return type (with description), errors (status codes or error types with conditions), and example (request + response for HTTP, input + output for functions).'

For HTTP APIs: 'Document endpoints in this order: method + path, description, authentication requirements, request parameters (path, query, body with types), response (status code, body shape), error responses (status codes with descriptions), and a curl example. Use consistent format across all endpoints — OpenAPI/Swagger is preferred for machine-readable docs.'

For code APIs: 'Use JSDoc (TypeScript), docstrings (Python), or doc comments (Go, Rust, Java) for public functions, classes, and types. Document what the function does (not how), parameters with types and descriptions, return value, and thrown errors. Generated docs (TypeDoc, Sphinx, godoc) should be deployable.'

Rule 3: Inline Code Comments

The rule: 'Comments explain why, not what. The code shows what happens — comments explain why it happens this way. Good: // Use binary search instead of linear because the list is always sorted and >10K items. Bad: // Loop through the array. Don't comment obvious code — trust the reader to understand basic patterns.'

For when to comment: 'Comment when: the code does something non-obvious, a workaround is needed for a known bug, a magic number has meaning (// 86400 = seconds per day), or a business rule drives the implementation. Don't comment when: the function name explains the purpose, the code follows a standard pattern, or the comment just repeats the code.'

For TODO comments: 'Use TODO(username): description format for work that needs to be done. Include a tracking issue link when one exists: TODO(alice): Optimize for large datasets - #1234. Never commit FIXME or HACK comments without a plan to address them.'

• Why, not what: explain reasoning, not obvious behavior
• No parroting: // increment counter above `counter++` adds nothing
• TODO format: TODO(name): description — link to issue when available
• Magic numbers: always comment with meaning — // 86400 = seconds per day
• Workarounds: always document the bug/reason and expected fix timeline

Rule 4: Technical Writing Style

The rule: 'Write in active voice, present tense. "The function returns a user" not "A user will be returned by the function." Use second person for instructions: "Run the migration" not "The migration should be run." Keep sentences under 25 words. One concept per paragraph. Use concrete examples instead of abstract descriptions.'

For consistency: 'Use American English spelling (customize, not customise). Use Oxford commas. Use code formatting for: file names (CLAUDE.md), command names (rulesync pull), variable names (userId), and technical terms on first use (CORS). Use bold for UI elements and key terms. Use italics sparingly.'

For structure: 'Use numbered lists for sequential steps, bullet lists for unordered items. Use headings hierarchically — never skip levels. Use tables for comparisons with more than 3 items. Use admonitions (note, warning, tip) for callout content. Keep documentation scannable — readers skim, they don't read linearly.'

Rule 5: Changelogs and PR Descriptions

The rule: 'Changelogs follow Keep a Changelog format: Added, Changed, Deprecated, Removed, Fixed, Security sections. Each entry is one line with a present-tense description: Added user search endpoint with pagination. Link to the PR or issue when available. Version headers use semantic versioning.'

For PR descriptions: 'Every PR description includes: Summary (what changed and why, 2-3 sentences), Changes (bullet list of specific modifications), Testing (how you verified it works), and Screenshots (for UI changes). Use the PR template if one exists. Never submit a PR with an empty description.'

For commit messages: 'Use conventional commits format: type(scope): description. Types: feat, fix, docs, refactor, test, chore. Scope is the area affected. Description is imperative present tense: "add user search" not "added user search." Keep the subject line under 72 characters. Add a body for context when the subject isn't self-explanatory.'

• Changelog: Keep a Changelog format — Added, Changed, Fixed, Security
• PR description: Summary + Changes + Testing + Screenshots — never empty
• Commits: type(scope): description — feat, fix, docs, refactor, test, chore
• Subject line under 72 chars — imperative present tense — body for context

Complete Documentation Rules Template

Consolidated rules for all documentation contexts.

• README: h1 + description + badges + Getting Started + Usage + Contributing + License
• API docs: description + params + return + errors + example for every endpoint/function
• Comments: why not what — no parroting — TODO(name) with issue links
• Style: active voice, present tense, <25 word sentences, concrete examples
• Changelogs: Keep a Changelog format — present tense, linked to PRs
• PR descriptions: Summary + Changes + Testing + Screenshots — never empty
• Commits: conventional commits — type(scope): imperative description
• markdownlint in CI — enforce heading hierarchy and consistent formatting