document-guideline

Documentation Standards

Defines how AI agents should create and maintain documentation at every level of a codebase — from high-level architecture down to individual source files and tests.

Guiding Principles

• Thorough: Every folder, source file, and test suite should be documented
• Design-first: Write documentation before writing code
• Self-describing: Each component explains its own purpose and public surface

Documentation Layers

A well-documented project maintains three layers:

1. Architecture docs (docs/) — Design decisions, system overviews, and workflows
2. Folder READMEs (README.md in each directory) — Purpose and layout of that directory
3. Interface docs (.md companion files next to source) — Public and internal API reference

---

Layer 1: Architecture Documentation

Where: docs/ directory

Purpose: Capture high-level design rationale so future contributors understand why the system is shaped the way it is.

Create or update when:

• Planning a new subsystem or major feature
• Making architectural decisions with trade-offs worth recording
• Introducing workflows or processes that span multiple modules

Writing tips:

• Explain the reasoning behind decisions, not just the outcome
• Note alternatives that were considered and why they were rejected
• Use diagrams or examples where they add clarity
• Keep docs in sync with the actual implementation

Skip architecture docs when:

• The information belongs at the source-file level instead
• The decision is temporary or experimental
• It would duplicate content already written elsewhere

---

Layer 2: Folder READMEs

Rule: Every non-hidden directory should contain a README.md.

Purpose: Let a developer landing in any folder understand what it contains and how files are organised.

When to create: Whenever a new directory is added to the project.

What to include:

1. A one- or two-sentence description of the folder's purpose
2. The types of files it contains
3. (Optional) A short list of key files with one-line descriptions

Keep it concise — a few lines is fine for simple folders; longer explanations are welcome for complex modules.

---

Layer 3: Source Interface Documentation

Rule: Every source file should have a companion .md file documenting its interfaces.

Applies to: .py, .ts, .js, .c, .cpp, .go, .rs, and similar source files.

Naming: Match the source file name — handler.py gets handler.md, parser.cpp gets parser.md.

Required sections:

External Interface (Public API)

Document everything the outside world can call:

• Function and method signatures
• Class constructors and key attributes
• Expected inputs, outputs, and error conditions
• Module-level exports or entry points

Internal Helpers (Private API)

Document implementation details worth explaining:

• Private functions and their roles
• Internal data structures
• Non-obvious algorithms or logic

---

Test Documentation

Rule: Every test file should explain what it verifies.

Acceptable formats:

• Inline comments within the test file (best for simple, self-explanatory tests)
• Companion .md file (better for complex test suites covering many scenarios)

What to document per test:

• The feature or behaviour under test
• The expected outcome
• Any required setup or preconditions

---

Development Workflow

This documentation standard pairs naturally with a design-first workflow:

1. Documentation — Write or update docs that describe the intended behaviour
2. Tests — Write tests that verify the documented behaviour
3. Implementation — Write code that makes the tests pass

Following this order ensures documentation stays ahead of code rather than lagging behind.

Temporary inconsistency is acceptable on feature branches where implementation is still in progress. However, by the time work is merged into the main branch, documentation must accurately reflect the code.

---

Quick Reference

What to document	Where	When
Architecture & design decisions	docs/	New subsystems, major features
Folder purpose & layout	README.md in each directory	Every new directory
Public & internal APIs	.md companion to source file	Every source file
Test intent & coverage	Inline comments or companion .md	Every test file