mosaicstack/stack
1
0
Fork 1
Code Issues 246 Pull Requests 7 Actions Packages Projects Releases 15 Wiki Activity

docs: define documentation information architecture

Browse Source
This commit is contained in:
Jason Woltje
2026-08-10 15:15:02 -05:00
parent 698655d40a
commit 205cc0d7a1
1 changed files with 182 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/2026-08-10-docs-information-architecture-design.md
+182
View File
@@ -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/<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:
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.