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:

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/<chapter>/`	The docs root
Installation, deployment, or recovery procedure	`docs/ADMIN-GUIDE/<chapter>/`	`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/<task-id>-<slug>.md`	The docs root or a canonical guide
Review, QA, audit, security, or deferral evidence	`docs/reports/<category>/`	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:

Cover one concern or workflow.
Use a descriptive, lowercase kebab-case filename, except for established root control files and required API filenames.
Begin with a clear title and a short purpose statement.
Declare status and audience when the page is more than a simple index.
Identify prerequisites, source-of-truth dependencies, and related pages.
State whether examples and commands are current, illustrative, or held/non-operative.
Include an owner or maintenance responsibility when the content is operationally sensitive.

Recommended front matter for canonical pages:

---
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:

Inventory current pages and classify each by audience, purpose, status, and source-of-truth role.
Move canonical content into the target tree without changing meaning unless the migration task explicitly includes a rewrite.
Update all repository links, source comments, tests, and SITEMAP.md in the same logical change.
Preserve historical evidence in reports/, tasks/, releases/, or archive/ rather than mixing it into current guides.
Treat _old_structure/ as read-only during migration. It may be removed only after all required links and source references are resolved.
Do not add new content to docs/mosaic-stack/; the empty directory is retired by this design.
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.

11 KiB Raw Blame History