Docs Guide

Purpose

Keep documentation organized, current, and easy to navigate as the project scales.

Structure Rules

• Single source of truth: each topic has one canonical doc.
• Legacy docs: mark clearly and link to the canonical version.
• No duplicates: if a new doc overlaps, merge and delete or mark legacy.
• Use the taxonomy:
  • planning/ for vision, roadmap, and high-level plans.
  • technical/ for specs and system design.
  • operations/ for runbooks, deployment, and security.
  • business/ for pricing and financials.
  • legal/ for legal templates.
  • templates/ for reusable doc templates.

Naming Conventions

• Use ALL_CAPS for major documents (e.g., STORE_PLATFORM_PLAN.md).
• Use clear nouns (e.g., STORE_PROVISIONING_SPEC.md).
• Avoid duplicates such as PRD.md in multiple folders unless one is marked legacy.

Front Matter (New or Updated Docs)

Add front matter to new or significantly updated docs:

---
owner: "Team or person"
status: "Draft | Active | Deprecated"
last_reviewed: "YYYY-MM-DD"
classification: "Public | Internal | Restricted"
---

Existing docs can be updated gradually.

Security Classification

• Public: safe to share externally.
• Internal: default; company-only.
• Restricted: sensitive (security, credentials, or vendor contracts).

Never store secrets in docs. Use docs/CREDENTIALS.md for placeholders only.

Update Process

When adding or changing docs:

1. Update docs/README.md structure + quick links.
2. Ensure the doc has an owner and clear purpose.
3. If replacing a doc, mark the old one as legacy.
4. Add front matter and classification (see above).

Canonical vs Legacy

• Canonical docs are linked in docs/README.md.
• Legacy docs must include a note at the top:
  • "Legacy - superseded by "

ADRs (Architecture Decision Records)

• Store ADRs in docs/technical/adr/.
• Use ADR_TEMPLATE.md and name new ADRs ADR_YYYYMMDD_short_title.md.

Docs Lint

Run python3 scripts/docs_lint.py (or make docs-lint) to check:

• Broken internal links
• Missing legacy banners

Local Hooks (Recommended)

Enable the check-only docs hook:

make hooks-install