Documentation Standards

Get this document

Use these standards in your own project.

Download Documentation Standards Download SEO Guide Doc components View all on GitHub

Documentation is structured data for both human and AI consumption. These standards ensure AI assistants can effectively help with your project across all phases — development, deployment, operations, and user support.

The 7 principles

1. Structured Data Over Prose

Use tables, JSON, YAML, and code blocks instead of paragraphs.

Bad:

The database requires a PostgreSQL connection string. You need to set the DATABASE_URL environment variable to something like postgresql://postgres:secret@localhost:5432/mydb. Make sure the database is running first.

Good:

Variable	Format	Example	Required
DATABASE_URL	postgresql://user:pass@host:port/db	postgresql://postgres:secret@localhost:5432/mydb	Yes

npm run db:test-connection
# Expected: "Connected successfully"

2. Explicit Context

Never assume prior knowledge. State what things are, not just how they work.

Bad: “Run the migration script.”

Good: “Run npm run db:migrate to apply pending database schema changes. This reads from ./migrations/ and applies them in order.”

3. Cause-Effect Relationships

Clear “if X then Y” statements. AI assistants need these to troubleshoot.

Symptom	Cause	Fix
ECONNREFUSED on port 5432	PostgreSQL not running	sudo systemctl start postgresql
relation does not exist	Migrations not applied	npm run db:migrate
authentication failed	Wrong credentials in DATABASE_URL	Check .env matches database user

4. Machine-Readable Formats

Consistent, parseable metadata. Use ISO dates, semantic versioning, and standardised status values.

**Status**: IN_DEVELOPMENT | TESTING | PRODUCTION
**Last Updated**: 2026-01-15
**Version**: 1.7.0

5. Searchable Content

Use consistent terminology, add keyword anchors, and maintain a clear heading hierarchy.

• One H1 per page (the title)
• H2 for major sections
• H3 for subsections
• Never skip levels (no H1 → H3)

6. Version-Stamped

Date all documentation updates. Include “Last Updated” on every file.

7. Cross-Referenced

Explicit links between related docs. Never assume the reader knows where to find related information.

Documentation layers

Layer	Phase	Documents
Development	Building	AGENTS.md, Architecture docs, Phase plans
Deployment	Setting up	DEPLOYMENT-GUIDE.md, OPERATIONS.md, API-REFERENCE.md
User	Using	USER-GUIDE.md, TROUBLESHOOTING.md, Configuration guides

Documentation components

The templates include reusable documentation components:

Component	Purpose
AI Navigation Header	Tells AI when to read each doc file
DOCS-MAP.md	Master index of all documentation with priorities
ADR Template	Architecture Decision Records with structured format
Metadata Block	Machine-readable frontmatter for any document

AI Navigation Header

Add to the top of documentation files to help AI assistants decide whether to read them:

<!-- AI NAVIGATION
Primary purpose: API authentication and authorization
Read when: user asks about auth, login, tokens, or permissions
Skip when: user asks about UI, frontend, or styling
Related: DEPLOYMENT-GUIDE.md (token configuration), API-REFERENCE.md
-->

Architecture Decision Records

Use the ADR template for significant decisions:

# ADR-001: Use JWT for API Authentication

**Status**: Accepted
**Date**: 2026-01-15
**Decision**: Use JWT tokens with 1-hour expiry for API auth

## Context
[Why this decision was needed]

## Considered Options
1. Session cookies
2. JWT tokens
3. API keys

## Decision
JWT tokens because [reasons]

## Consequences
- [Positive]
- [Negative]

Anti-patterns

Anti-pattern	Why it’s bad	Fix
Prose-only docs	AI can’t extract structured data	Use tables and code blocks
No dates	Can’t tell if docs are current	Add “Last Updated” everywhere
Assumed knowledge	AI starts from zero each session	State what things are
Marketing language	”Production-ready” is meaningless	State actual status
Broken cross-refs	AI follows dead links	Verify links at each checkpoint

Full reference

The complete documentation standards document (1300+ lines with examples, templates, and an ADR walkthrough) is included at DOCUMENTATION-STANDARDS.md.