Mav Bp Documentation

Documentation Standards

Ensure all projects have accurate, structured, and up-to-date documentation that serves both human developers and AI agents.

Principles

1. All projects must have documentation — no project is too small for a README and basic architecture overview
2. Human-readable but AI-optimised — documentation is written for humans first, but structured so AI agents can parse and act on it reliably
3. Kept up to date — stale documentation is worse than no documentation; freshness is enforced via workflow
4. Enforced via workflow — documentation updates are part of the development process, not an afterthought
5. Documentation as code — docs live in the repository alongside the code they describe, versioned and reviewed together

Minimum Documentation Requirements

Every project must have the following at a minimum:

README Structure

A README should contain, in order:

1. Project name and one-line description
2. Prerequisites — runtime versions, system dependencies
3. Quick start — clone, install, run (copy-pasteable commands)
4. Development — how to run tests, lint, build
5. Deployment — how and where it deploys (or link to deployment docs)
6. Contributing — link to contributing guide or inline conventions

Documentation Structure and Organisation

• Keep docs close to the code they describe — prefer docs/ in the repo over external wikis
• Use flat structures for small projects; use subdirectories (docs/api/, docs/guides/, docs/architecture/) for larger ones
• Name files descriptively — docs/database-migrations.md, not docs/db.md
• Use consistent heading hierarchy — # for title, ## for sections, ### for subsections
• Include diagrams where they clarify — Mermaid syntax preferred for version-controlled diagrams

Writing for Dual Audience

Documentation serves two audiences: human developers and AI agents. Optimise for both.

Human-Readable

• Write in plain language, avoid unnecessary jargon
• Use examples liberally — show, don't just tell
• Explain the "why" alongside the "what"
• Keep paragraphs short and scannable

AI-Agent-Optimised

• Dense and precise — avoid filler words and vague statements; every sentence should carry information
• Structurally consistent — use the same heading patterns, table formats, and section ordering across documents
• Machine-parseable — use tables, lists, and code blocks rather than prose for structured data
• Explicit over implicit — state assumptions, constraints, and boundaries directly rather than relying on context
• Self-contained sections — each section should be understandable without reading the entire document

Documentation Freshness

Stale documentation actively harms a project. Freshness is enforced, not hoped for.

Rules

• Code changes require doc updates — if a PR changes behaviour, public APIs, configuration, or setup steps, the corresponding documentation must be updated in the same PR
• Broken docs are bugs — treat outdated documentation with the same urgency as broken tests
• Review docs in code review — reviewers must check that documentation matches the change

Enforcement

• Pre-commit hooks or CI checks can flag PRs that modify source files without touching relevant docs
• Workflow skills (do-tech-docs, do-docs) enforce documentation creation and updates as part of the development process
• The code-review agent checks for documentation coverage

CLAUDE.md and Project-Level AI Instructions

Every project should have a CLAUDE.md at the repository root. This file provides context and instructions to AI agents working on the codebase.

What to Include

• Project overview — what the project does, its architecture at a glance
• Build and run commands — exact commands to install, build, test, lint, deploy
• Key conventions — naming, file structure, patterns the project follows
• What to avoid — anti-patterns, deprecated approaches, files not to touch
• Architecture notes — how components relate, data flow, key abstractions

What NOT to Include

• Secrets, credentials, or environment-specific values
• Information that changes every sprint — keep it stable
• Duplicates of what is already in README or other docs — link instead

What NOT to Document

• Implementation details that change frequently — internal algorithms, private function behaviour, temporary workarounds. These go stale immediately.
• Auto-generated content — API docs generated from OpenAPI specs, type docs generated from code. Commit the generator config, not the output.
• Obvious code — well-named functions and types are self-documenting. Don't write docs that restate what the code already says.
• Aspirational features — don't document what the system might do someday. Document what it does now.

Documentation Review in Code Review

When reviewing a PR, check documentation alongside code:

Detailed Documentation Workflows

For creating or updating documentation, use the dedicated documentation skills:

• do-tech-docs — technical documentation standards covering document structure, writing style, file organisation, Mermaid diagrams, and validation
• do-docs — workflow for creating, restructuring, or updating technical documentation

Detecting Documentation Issues

When reviewing code or auditing a project, flag these patterns:

Source: thermiteau/maverick — distributed by TomeVault.