diff --git a/docs/plans/2026-08-10-docs-information-architecture-design.md b/docs/plans/2026-08-10-docs-information-architecture-design.md new file mode 100644 index 00000000..a4c06410 --- /dev/null +++ b/docs/plans/2026-08-10-docs-information-architecture-design.md @@ -0,0 +1,182 @@ +# Documentation Information Architecture Design + +**Status:** Approved +**Date:** 2026-08-10 +**Scope:** Establish the canonical structure and authoring rules for `docs/` before migrating or rewriting existing documentation. + +## Goal + +Create a clean, human-readable, Obsidian-compatible documentation system for Mosaic Stack. The system must make the relationships between requirements, architecture, guides, API contracts, operational procedures, evidence, and work tracking visible without duplicating canonical content. + +## Decision + +Use a single root-level documentation atlas in `docs/README.md`, organized around audience-specific guide books and dedicated artifact directories. Retire `docs/mosaic-stack/` as a content boundary; it adds no useful ownership distinction once the documentation system has explicit root guides and cross-links. + +The target structure is: + +```text +docs/ +├── README.md +├── PRD.md +├── TASKS.md +├── SITEMAP.md +│ +├── USER-GUIDE/ +│ ├── README.md +│ ├── getting-started/ +│ ├── concepts/ +│ ├── workflows/ +│ └── troubleshooting/ +│ +├── ADMIN-GUIDE/ +│ ├── README.md +│ ├── installation/ +│ ├── configuration/ +│ ├── deployment/ +│ ├── operations/ +│ ├── security/ +│ └── recovery/ +│ +├── DEVELOPER-GUIDE/ +│ ├── README.md +│ ├── architecture/ +│ │ ├── README.md +│ │ ├── system-overview.md +│ │ ├── component-map.md +│ │ ├── data-flow.md +│ │ ├── security-model.md +│ │ ├── decisions/ +│ │ └── rfcs/ +│ ├── packages/ +│ ├── local-development/ +│ ├── testing/ +│ ├── contributing/ +│ └── integrations/ +│ +├── API/ +│ ├── README.md +│ ├── OPENAPI.yaml +│ └── ENDPOINTS.md +│ +├── assets/ +├── reports/ +│ ├── code-review/ +│ ├── documentation/ +│ ├── qa/ +│ ├── security/ +│ └── deferred/ +├── tasks/ +├── plans/ +├── scratchpads/ +├── releases/ +├── archive/ +└── _old_structure/ # temporary migration quarantine; read-only +``` + +`docs/plans/` is a workflow directory for approved design and implementation plans. It is not a substitute for the canonical requirements document, active task ledger, or guide books. + +## Information architecture + +### Root control documents + +- `docs/README.md` is the documentation contract, placement guide, and top-level entry point. +- `docs/PRD.md` is the canonical product and requirements source. Requirements must not be silently redefined in guides or reports. +- `docs/TASKS.md` is the active orchestrator rollup. Its single-writer policy remains authoritative. +- `docs/SITEMAP.md` is the complete human navigation index. It must be updated when canonical pages are added, moved, renamed, or retired. + +### Audience books + +- `USER-GUIDE/` contains end-user workflows, user-visible behavior, concepts needed to operate the product, and user troubleshooting. +- `ADMIN-GUIDE/` contains installation, configuration, deployment, operations, security controls, recovery, and incident procedures. +- `DEVELOPER-GUIDE/` contains architecture, package/component documentation, local development, testing, contribution rules, and integration authoring. +- `API/` contains the machine-readable OpenAPI contract and its human-readable endpoint index. + +Audience books are task-oriented. They link to canonical architecture, requirements, API, and operational pages rather than copying those pages. + +### Artifact directories + +- `assets/` contains diagrams and documentation media referenced by canonical pages. +- `reports/` contains evidence and findings. Reports are informative and do not override the PRD or normative contracts. +- `tasks/` contains archived task snapshots and orchestrator learnings. Active orchestration remains in root `TASKS.md`. +- `plans/` contains approved design and implementation plans. +- `scratchpads/` contains active, task-specific working notes and verification evidence. Scratchpads are not product documentation. +- `releases/` contains release notes and release-specific migration or compatibility notes. +- `archive/` contains superseded but intentionally retained documentation. Archived pages must state their replacement or reason for retention. +- `_old_structure/` is a temporary migration quarantine. It is read-only, is not indexed as current documentation, and is not an authoring destination. + +## Placement rules + +| Content | Required location | Do not place it in | +| ----------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------- | +| Product requirements and acceptance criteria | `docs/PRD.md` or an explicitly scoped PRD under a guide/workstream | A scratchpad, report, or README-only note | +| Active task status | `docs/TASKS.md` | A guide page or personal scratchpad | +| User workflow | `docs/USER-GUIDE//` | The docs root | +| Installation, deployment, or recovery procedure | `docs/ADMIN-GUIDE//` | `README.md` or a report | +| Architecture, component, package, ADR, or RFC content | `docs/DEVELOPER-GUIDE/architecture/` or its relevant developer chapter | `docs/mosaic-stack/` or the docs root | +| API contract | `docs/API/OPENAPI.yaml` and `docs/API/ENDPOINTS.md` | A guide-only description | +| Documentation navigation | `docs/SITEMAP.md` | A duplicated ad-hoc index | +| Design or implementation plan | `docs/plans/` | `docs/scratchpads/` | +| Active task working notes | `docs/scratchpads/-.md` | The docs root or a canonical guide | +| Review, QA, audit, security, or deferral evidence | `docs/reports//` | A canonical guide page | +| Archived task snapshot | `docs/tasks/` | Root `TASKS.md` unless it is active | +| Release notes | `docs/releases/` | The docs root | +| Diagram or image | `docs/assets/` or an owning chapter asset directory | An external personal path | +| Superseded documentation | `docs/archive/` | `_old_structure/` after migration completes | + +When a page appears to fit multiple locations, classify it by its primary reader and purpose, then link it from the other relevant indexes. Do not create copies to satisfy multiple audiences. + +## Page conventions + +Every canonical Markdown page should: + +1. Cover one concern or workflow. +2. Use a descriptive, lowercase kebab-case filename, except for established root control files and required API filenames. +3. Begin with a clear title and a short purpose statement. +4. Declare status and audience when the page is more than a simple index. +5. Identify prerequisites, source-of-truth dependencies, and related pages. +6. State whether examples and commands are current, illustrative, or held/non-operative. +7. Include an owner or maintenance responsibility when the content is operationally sensitive. + +Recommended front matter for canonical pages: + +```yaml +--- +title: Human-readable page title +type: guide +audience: developer +status: current +--- +``` + +Allowed `type` values include `guide`, `concept`, `reference`, `decision`, `rfc`, and `runbook`. Allowed `audience` values are `user`, `admin`, `developer`, and `all`. Allowed `status` values are `current`, `draft`, `deprecated`, and `historical`. + +## Obsidian and link conventions + +- Use Obsidian wikilinks for relationship-oriented internal references, for example `[[DEVELOPER-GUIDE/architecture/component-map|Component map]]`. +- Use normal relative Markdown links in `SITEMAP.md` and book `README.md` indexes so links render on Git hosting platforms. Obsidian can resolve these links too. +- Use `Related`, `Depends on`, and `Referenced by` sections when a page participates in a meaningful documentation relationship. +- Link to stable page paths, not transient line numbers or branch URLs. +- Omit `.md` in wikilinks. Include an alias when the file path is not a readable label. +- Use standard Markdown links for external URLs, source files, commands, and API paths. +- Do not rely on a link to `_old_structure/` as a current navigation path. Historical references must explain why the archived page is retained and point to its replacement. + +## Migration rules + +This design phase does not move or rewrite content. During later migration: + +1. Inventory current pages and classify each by audience, purpose, status, and source-of-truth role. +2. Move canonical content into the target tree without changing meaning unless the migration task explicitly includes a rewrite. +3. Update all repository links, source comments, tests, and `SITEMAP.md` in the same logical change. +4. Preserve historical evidence in `reports/`, `tasks/`, `releases/`, or `archive/` rather than mixing it into current guides. +5. Treat `_old_structure/` as read-only during migration. It may be removed only after all required links and source references are resolved. +6. Do not add new content to `docs/mosaic-stack/`; the empty directory is retired by this design. +7. For documents referenced by executable tests or source code, update those references deliberately and verify them before deleting the old path. + +## Acceptance criteria + +- `docs/README.md` defines the complete target tree and placement rules. +- The target tree has no `docs/mosaic-stack/` content boundary. +- Agents can determine where to put product docs, plans, task notes, reports, scratchpads, releases, and archives without guessing. +- The rules support both Obsidian graph navigation and Git-hosted Markdown navigation. +- The design distinguishes normative sources from evidence and working notes. +- Migration can proceed incrementally without treating `_old_structure/` as current documentation.