Fleshed out documentation

2026-02-28 17:41:00 +03:00
parent 828cbcc822
commit aa607b9b6e
13 changed files with 332 additions and 9 deletions
@@ -1,11 +1,36 @@
-# Docs Notes (MVP Alignment)
+# Documentation Index

-## High-Level Takeaways
- The MVP roadmap aligns with Phase 1 goals but needs tighter documentation around provider readiness and async strategy.
- ExecPlan references drift between `AGENTS.md` and `PLANS.md` should be resolved to avoid conflicting guidance.
- Observability and operational visibility are thin; errors are stored but not surfaced through clear runbooks/dashboards.
+This directory is the source of truth for product, engineering, and ops documentation. Keep it current as features change.

-## Near-Term Focus
- Make ExecPlan references consistent and keep active plans clearly labeled.
- Document whether MVP uses async jobs (and which system) or remains synchronous with strict timeouts.
- Keep `docs/risks.md` current as gaps are closed.
+## Start Here
+
+- Project overview and setup: `README.md` (repo root)
+- Architecture overview: `docs/architecture.md`
+- Active ExecPlan: `docs/execplans/booking-notifications.md`
+- Known risks and gaps: `docs/risks.md`
+
+## Documentation Standards
+
+See `docs/documentation.md` for documentation goals, update triggers, and templates.
+
+## Docs Map
+
+- `docs/architecture.md`: System architecture, boundaries, and MVP async/observability decision.
+- `docs/adr/`: Architecture Decision Records (ADRs). New cross-cutting decisions must land here.
+- `docs/execplans/`: Execution plans for significant features or refactors.
+- `docs/runbooks/`: Operational runbooks and production checklists.
+- `docs/risks.md`: Tracked risks and gaps.
+- `docs/templates/`: Reusable templates (ADR, runbook).
+
+## Update Triggers (Quick Reference)
+
+- New external dependency, provider, or major flow: add an ADR in `docs/adr/`.
+- Change to booking/payment/auth logic: update `docs/architecture.md` and relevant runbook(s).
+- New operational procedure: add a runbook in `docs/runbooks/`.
+- Close or add a significant risk: update `docs/risks.md`.
+
+## Ownership And Review
+
+- Authors own freshness: if you touch an area, update the docs in the same PR.
+- New production flows require at least one runbook.
+- Avoid duplicating instructions; link to the single source of truth.