10 — Proposed Documentation Structure

Covers task 12. How BitVault’s documentation should be organized so each audience (contributor, operator, integrator, end user, and the portfolio reviewer) finds what they need. Built on the Diátaxis framework — four modes with different purposes — plus the decision/architecture records that already exist in this set.

The guiding rule: documentation has audiences and modes; do not mix them. A tutorial is not a reference; an ADR is not a how-to. Each document knows what it is.

1. The Diátaxis quadrants (and who they serve)

Mode Purpose Audience Answers
Tutorials Learning by doing newcomers “Get me started”
How-to guides Goal-oriented recipes operators, integrators “How do I X?”
Reference Information lookup all technical users “What exactly is X?”
Explanation Understanding & rationale contributors, reviewers “Why is it like this?”

ADRs and the architecture set (01–09) are Explanation. The API spec is Reference. Deploy guides are How-to. A “deploy your first vault” is a Tutorial.

2. Proposed docs/ tree

docs/
├── README.md                       # docs home + reading guide by audience (see §3)
│
├── architecture/                   # EXPLANATION — the design (this set)
│   ├── 01-critique-and-risks.md
│   ├── 02-product-goals.md
│   ├── 03-system-requirements.md
│   ├── 04-bounded-contexts.md
│   ├── 05-service-boundaries.md
│   ├── 06-high-level-architecture.md
│   ├── 07-repository-structure.md
│   ├── 08-data-model.md
│   ├── 09-evolution-roadmap.md
│   └── 10-documentation-structure.md
│
├── adr/                            # EXPLANATION — decisions (immutable, numbered)
│   ├── README.md                   #   index + status legend
│   └── NNNN-*.md
│
├── diagrams/                       # shared visual assets + index (task 11)
│   └── README.md                   #   catalog of all Mermaid diagrams + where they live
│
├── tutorials/                      # TUTORIALS — learning paths
│   ├── self-host-quickstart.md     #   "compose up" your first vault (lite tier)
│   ├── first-sync-with-the-cli.md  #   upload, share, sync via the CLI
│   └── deploy-on-kubernetes.md     #   Helm install, end to end
│
├── how-to/                         # HOW-TO — task recipes
│   ├── operations/                 #   operators
│   │   ├── configure-storage-provider.md   # MinIO/S3/R2/GCS/Azure
│   │   ├── choose-a-deployment-tier.md     # lite/standard/full (ADR-0012)
│   │   ├── set-up-sso-oidc.md
│   │   ├── back-up-and-restore.md
│   │   ├── scale-and-tune.md
│   │   └── rotate-encryption-keys.md       # ADR-0014
│   └── integration/                #   integrators
│       ├── authenticate-with-api-tokens.md
│       ├── upload-large-files.md           # presign→transfer→commit (ADR-0011)
│       ├── consume-webhooks.md
│       └── use-the-rest-api.md
│
├── reference/                      # REFERENCE — precise lookup
│   ├── api/                        #   generated OpenAPI (ADR-0003/0015) + rendered docs
│   ├── cli/                        #   generated CLI command reference
│   ├── configuration.md            #   every env var / config key, per tier
│   ├── events.md                   #   the Published Language: event catalog (ADR-0006)
│   ├── data-model.md               #   pointer to architecture/08 + schema reference
│   └── error-codes.md              #   the apperr taxonomy (ADR-0015)
│
├── runbooks/                       # HOW-TO (operational, incident-time)
│   ├── on-call-overview.md
│   ├── outbox-or-consumer-lag.md   #   eventual-consistency incidents (ADR-0006/0013)
│   ├── reindex-search.md           #   rebuild the derived index (ADR-0009)
│   ├── orphaned-blob-gc.md         #   dual-write reconciliation (ADR-0004)
│   └── restore-from-backup.md
│
├── security/                       # EXPLANATION + REFERENCE
│   ├── threat-model.md             #   STRIDE over the contexts; trust boundaries
│   ├── tenant-isolation.md         #   RLS model (ADR-0007)
│   ├── data-protection.md          #   encryption, key mgmt (ADR-0014)
│   └── disclosure.md               #   SECURITY.md / responsible disclosure
│
└── contributing/                   # EXPLANATION + HOW-TO (contributors)
    ├── development-setup.md
    ├── coding-standards.md
    ├── testing-strategy.md         #   unit/contract/e2e/load/chaos (07 test/)
    ├── working-with-proto.md       #   buf workflow (ADR-0003)
    └── adr-process.md              #   how/when to write an ADR

Top-level project files complement this tree: README.md (what/why + quickstart pointer), CONTRIBUTING.md → docs/contributing/, SECURITY.md → docs/security/disclosure.md, CHANGELOG.md.

3. Reading guide by audience (goes in docs/README.md)

4. Documentation principles (how it stays good)

  1. Docs-as-code. Markdown in-repo, reviewed in PRs, versioned with the code that changes them. A behavior change and its doc change land together (monorepo, ADR-0002).
  2. Generate the volatile parts. API reference (OpenAPI), CLI reference, config reference, and the event catalog are generated from source/proto — never hand-maintained, so they cannot drift (R8/ADR-0003).
  3. ADRs are immutable. Decisions are superseded, never silently edited; history is the value.
  4. Diagrams live next to their narrative and are catalogued in diagrams/ (task 11). Mermaid in Markdown so they render on the platform and diff in PRs.
  5. One mode per document. Respect Diátaxis: don’t turn a tutorial into a reference dump or an ADR into a how-to.
  6. Every NFR/risk traces to a doc. Risks (01) and NFRs (03) link to the ADR that addresses them and the runbook that operates them — so the docs form a connected graph, not a pile.

5. What to write first (don’t boil the ocean)

Documentation is gated like features (09) — write what the current phase needs, no speculative docs:

The architecture and ADR docs that already exist are deliberately the first thing written — because, per the brief, this is a design review before development begins.