# Mav Bp Documentation > Documentation conventions for all projects. Covers minimum documentation requirements, documentation freshness enforcement, AI-readable structure, and the relationship between human and machine audiences. Applied when creating or reviewing project documentation. Use when this capability is needed. - Skill: `tomevault-io/mav-bp-documentation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/mav-bp-documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mav-bp-documentation/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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: | Document | Location | Purpose | | --------------------- | --------------------------------- | --------------------------------------------------------------- | | README | `README.md` (repo root) | Project purpose, quick start, prerequisites, how to run/test | | Architecture overview | `docs/architecture.md` or equiv. | System components, data flow, key design decisions | | Setup guide | README or `docs/setup.md` | Step-by-step instructions to go from clone to running locally | | API docs | `docs/api/` or inline | Required if the project exposes an API (REST, GraphQL, CLI, SDK)| | CLAUDE.md | Repo root | AI agent instructions — see dedicated section below | ### 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: | Check | Action | | -------------------------------------------------- | ------------------------------------------------------------ | | PR changes a public API | Verify API docs are updated | | PR changes setup/install steps | Verify README or setup guide is updated | | PR adds a new component or service | Verify architecture docs are updated | | PR changes configuration or environment variables | Verify relevant docs reflect the change | | PR introduces a new pattern or convention | Verify CLAUDE.md or contributing guide is updated | | PR deletes or renames a feature | Verify old documentation references are removed or updated | ## 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: | Pattern | Issue | Fix | | ------------------------------------------------ | ---------------------------- | -------------------------------------------------------- | | No README.md in repo root | Missing essential docs | Create README with minimum required sections | | README has no setup/run instructions | Unusable for new developers | Add quick-start commands | | Code change without doc update | Documentation drift | Update relevant docs in the same PR | | No CLAUDE.md | AI agents lack context | Create CLAUDE.md with project overview and commands | | Docs reference deleted features or old APIs | Stale documentation | Remove or update stale references | | Architecture docs missing for multi-service project | Unclear system design | Create architecture overview with component diagram | | Inline comments restating obvious code | Noise, not documentation | Remove; write higher-level docs instead | | Documentation in external wiki only | Not versioned with code | Move to repo `docs/` directory | --- > Source: [thermiteau/maverick](https://github.com/thermiteau/maverick) — distributed by [TomeVault](https://tomevault.io).