Documentation

1. Core Philosophy: Minimum Viable Documentation (MVD)

We optimize for accuracy over volume. A small set of fresh, accurate documents is infinitely better than a massive library of abandoned guides.

Adopt "Docs as Code": Technical documentation should be written in Markdown, live directly in the Git repository alongside the code, and go through the exact same Pull Request review process.

Delete Dead Docs: Outdated documentation is actively more dangerous than no documentation, as it leads to poor decision-making and wasted debugging time. If a document is wrong and you don't have the capacity to update it, delete it.

State the Audience: Always define who the document is for at the very top. An infrastructure guide for DevOps requires a completely different context than an API guide for a frontend developer.

2. The Proximity Rule

Documentation must live as close to the logic it describes as physically possible. The further away it is, the faster it rots.

Tier 1 (The Code): Self-documenting variable names, strict TypeScript types, and inline comments.

Tier 2 (The Repository): README.md, CONTRIBUTING.md, and local docs/ folders for setup, testing, and architecture.

Tier 3 (The Central Wiki): Confluence or Notion should be strictly reserved for high-level cross-system diagrams, non-technical product requirements (PRDs), onboarding checklists, and company policies. Never put instructions on how to boot a local development server in a Wiki.

3. Code-Level Commenting Standards

Do not clutter the codebase with redundant comments that just repeat what the syntax already says.

Explain "Why", Not "What": The code dictates what is happening and how it executes. Inline comments must strictly exist to explain why.

Bad: // Map over the users array to extract IDs

Good: // Mapping in memory instead of executing a DB aggregation to avoid hitting Payload CMS rate limits on this specific endpoint

Name Over Documentation: If a function or variable requires a comment to explain what it represents, the name has failed. Refactor the name to be semantically clear instead.

4. Repository Requirements

Every repository in your ecosystem must contain the following structural documentation:

The README.md Trailhead: This must serve as the immediate entry point. It must explicitly cover: what the project is, prerequisite installations (Node versions, Docker), how to boot it locally, and how to execute the test suite.

Architecture Decision Records (ADRs): When the team makes a significant technical choice (e.g., "Choosing Next.js App Router over Vite for this project" or "Implementing Redis for caching"), document it in a docs/adr/ folder. State the context, the decision, and the trade-offs. This permanently ends the cycle of new engineers asking, "Why was it built this way?"

Quickstarts with Value: Do not just print "Hello World." Your setup documentation should guide developers to a point where they can execute a meaningful action, like successfully hitting a mock database or rendering the primary UI.

5. Pull Request Enforcement

Documentation rules mean nothing if they aren't enforced at the gate.

Synchronous Updates: Documentation must be updated in the exact same Pull Request as the code change.

The "No Orphaned Features" Rule: If an engineer's PR introduces a new environment variable, requires a new database index, or changes an API response shape, the PR must explicitly include the updates to .env.example, the API documentation, or the README.md. If it doesn't, reviewers must block the merge.