Skip to content

Commit f536846

Browse files
codemonkeychrisclaude
codemonkeychris
and
claude
committed
Add spec 021: docs folder reorganization
Proposes splitting docs/ into guide/reference/specs/research/pitch/reports plus a hidden _pipeline/ for doc-gen internals, so planning, research, and end-user documentation each have an obvious home. No files are moved in this change — spec only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent b3e126a commit f536846

1 file changed

Lines changed: 189 additions & 0 deletions

File tree

‎docs/spec/021-docs-reorganization.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# 021 — Docs Folder Reorganization
2+
3+
**Status:** Draft
4+
**Date:** 2026-04-17
5+
6+
## Overview
7+
8+
Reorganize `docs/` into four clearly-separated buckets — **end-user/dev documentation**, **planning** (specs, tasks, proposals), **research** (analysis, investigations, comparisons), and **pipeline internals** — plus small homes for pitch assets and point-in-time reports. The current layout mixes all of these at the top level and scatters loose files in `docs/` root, which makes it hard for new contributors to know what is authoritative, what is generated, and what is scratch work.
9+
10+
The end-user docs stay checked in as pre-rendered Markdown because the compilation pipeline needs a running WinUI host to capture screenshots and cannot run on hosted CI runners today.
11+
12+
---
13+
14+
## 1. Current Layout
15+
16+
```
17+
docs/
18+
├── apps/ # doc-pipeline: snippet-source Reactor apps (20 topics)
19+
├── bentobox.svg # pitch asset
20+
├── bugs/ # bug investigations
21+
├── compare/ # per-framework competitive analysis
22+
├── critical-review.md # research (root)
23+
├── design-targets/ # pitch/design reference images
24+
├── flux-ui-analysis.md # research (root)
25+
├── investigation/ # technical investigations
26+
├── output/ # compiled end-user docs (generated, committed)
27+
├── proposals/ # pre-spec ideas
28+
├── reactor-pitch.md # marketing (root)
29+
├── reference/ # dev-facing architecture deep dives
30+
├── spec/ # numbered design specs (+ archived/)
31+
├── tasks/ # per-spec implementation task lists
32+
├── templates/ # doc-pipeline: .md.dt templates (+ ai-author-skill.md)
33+
├── winui3-integration-proposals.md # pre-spec idea (root)
34+
└── worksummary/ # point-in-time activity report
35+
```
36+
37+
Problems:
38+
39+
- Five loose `.md` / `.svg` files at `docs/` root with no category.
40+
- `spec/`, `tasks/`, and `proposals/` are all planning artifacts but live as peers.
41+
- `critical-review.md`, `flux-ui-analysis.md`, `compare/`, `investigation/`, and `bugs/` are all research but are scattered.
42+
- `output/` reads like a build artifact, discouraging readers — but it is the website.
43+
- `apps/` and `templates/` are pipeline implementation, not docs, yet sit at the top of the tree.
44+
- No index or README tells a newcomer which folder is authoritative for what.
45+
46+
## 2. Target Layout
47+
48+
```
49+
docs/
50+
├── README.md # index: what each folder is for
51+
52+
├── guide/ # end-user docs (rendered site) — from output/
53+
│ ├── getting-started.md
54+
│ ├── layout.md, styling.md, …
55+
│ └── images/
56+
57+
├── reference/ # dev-facing architecture deep dives (unchanged)
58+
│ ├── state-and-hooks.md
59+
│ ├── reconciliation.md
60+
│ ├── native-differ.md
61+
│ └── localization-howto.md
62+
63+
├── specs/ # PLANNING (rename from spec/)
64+
│ ├── 001-theming-design.md … 021-docs-reorganization.md
65+
│ ├── archived/
66+
│ ├── tasks/ # per-spec implementation checklists
67+
│ └── proposals/ # pre-spec ideas
68+
│ ├── forms-data-entry.md
69+
│ └── winui3-integration.md # ← docs/winui3-integration-proposals.md
70+
71+
├── research/ # RESEARCH
72+
│ ├── critical-review.md # ← docs/critical-review.md
73+
│ ├── flux-ui-analysis.md # ← docs/flux-ui-analysis.md
74+
│ ├── compare/ # unchanged
75+
│ ├── investigations/ # rename from investigation/
76+
│ └── bugs/ # unchanged
77+
78+
├── pitch/ # marketing assets
79+
│ ├── reactor-pitch.md # ← docs/reactor-pitch.md
80+
│ ├── bentobox.svg # ← docs/bentobox.svg
81+
│ └── design-targets/ # ← docs/design-targets/
82+
83+
├── reports/
84+
│ └── work-summary/ # rename from worksummary/
85+
86+
└── _pipeline/ # doc-gen internals (not reader-facing)
87+
├── apps/ # ← docs/apps/
88+
├── templates/ # ← docs/templates/
89+
└── ai-author-skill.md # stays with the pipeline
90+
```
91+
92+
## 3. Move Map
93+
94+
| From | To |
95+
|---|---|
96+
| `docs/output/` | `docs/guide/` |
97+
| `docs/spec/` | `docs/specs/` |
98+
| `docs/spec/archived/` | `docs/specs/archived/` |
99+
| `docs/tasks/` | `docs/specs/tasks/` |
100+
| `docs/proposals/` | `docs/specs/proposals/` |
101+
| `docs/winui3-integration-proposals.md` | `docs/specs/proposals/winui3-integration.md` |
102+
| `docs/critical-review.md` | `docs/research/critical-review.md` |
103+
| `docs/flux-ui-analysis.md` | `docs/research/flux-ui-analysis.md` |
104+
| `docs/compare/` | `docs/research/compare/` |
105+
| `docs/investigation/` | `docs/research/investigations/` |
106+
| `docs/bugs/` | `docs/research/bugs/` |
107+
| `docs/reactor-pitch.md` | `docs/pitch/reactor-pitch.md` |
108+
| `docs/bentobox.svg` | `docs/pitch/bentobox.svg` |
109+
| `docs/design-targets/` | `docs/pitch/design-targets/` |
110+
| `docs/worksummary/` | `docs/reports/work-summary/` |
111+
| `docs/apps/` | `docs/_pipeline/apps/` |
112+
| `docs/templates/` | `docs/_pipeline/templates/` |
113+
| `docs/reference/` | unchanged |
114+
115+
All moves performed with `git mv` to preserve history.
116+
117+
## 4. Rationale
118+
119+
- **`guide/` + `reference/` split** matches the Rust, Vue, and React conventions for user-facing documentation. "Guide" = learn-by-doing topics; "reference" = deep dives and API contracts.
120+
- **`specs/` with `tasks/` and `proposals/` nested** makes the planning lifecycle visible: proposal → spec → tasks → archived. Keeps planning artifacts co-located instead of as top-level peers.
121+
- **`research/` consolidates** competitive analysis, investigations, and bug write-ups so readers can find "why did we decide X" without digging through the root.
122+
- **`_pipeline/` prefix** pushes doc-generator implementation below the fold. The leading underscore signals "this is plumbing, not docs." Alternative considered: move outside `docs/` entirely into `tools/doc-pipeline/` — rejected because the apps and templates are semantically paired with `guide/` outputs.
123+
- **Pre-compiled output stays committed** because screenshot capture requires a running WinUI host, which is not available on `ubuntu-latest` or `windows-latest` CI runners without a self-hosted agent. Renaming `output/` to `guide/` does not change the publish mechanism (GitHub-rendered Markdown browsing).
124+
- **Plural `specs/`** matches the existing `proposals/`, `tasks/`, `compare/` style and is the community convention.
125+
126+
## 5. Pipeline Code Impact
127+
128+
The doc compiler hardcodes the output path. Affected locations (incomplete — full audit part of the work):
129+
130+
| File | Change |
131+
|---|---|
132+
| `src/Reactor.Cli/Docs/*` (compile pipeline) | `docs/output/` → `docs/guide/`; `docs/apps/` → `docs/_pipeline/apps/`; `docs/templates/` → `docs/_pipeline/templates/` |
133+
| `docs/spec/013-doc-system-design.md` | Update all path references (lines 50, 55, 134, 238, 251, 257, 449, 457–461, 467, 492, 508, 529, 611) |
134+
| `docs/templates/ai-author-skill.md` → `docs/_pipeline/ai-author-skill.md` | Update all path references (lines 11, 14, 16, 31, 78, 81, 496) |
135+
| CI workflows under `.github/workflows/` | Audit for any `docs/output|apps|templates` references (current search found none, but re-check at execution time) |
136+
137+
## 6. Top-Level README Updates
138+
139+
`README.md` links to update:
140+
141+
- `docs/winui3-integration-proposals.md` → `docs/specs/proposals/winui3-integration.md`
142+
- `docs/reference/state-and-hooks.md` (unchanged path)
143+
- `docs/reference/reconciliation.md` (unchanged path)
144+
- `docs/reference/native-differ.md` (unchanged path — file currently missing but referenced)
145+
146+
## 7. New `docs/README.md`
147+
148+
A new index file at `docs/README.md` orients readers:
149+
150+
```markdown
151+
# Reactor Documentation
152+
153+
- **[guide/](guide/)** — User-facing documentation. Getting started, topic guides, screenshots.
154+
- **[reference/](reference/)** — Architecture deep dives for framework contributors.
155+
- **[specs/](specs/)** — Design specs, implementation tasks, and proposals.
156+
- **[research/](research/)** — Competitive analysis, investigations, bug write-ups.
157+
- **[pitch/](pitch/)** — Marketing materials and design targets.
158+
- **[reports/](reports/)** — Point-in-time reports (work summaries, metrics).
159+
- **_pipeline/** — Internals of the doc-generation pipeline. Not reader-facing.
160+
161+
The `guide/` folder is pre-rendered because screenshot capture requires a running
162+
WinUI host. To rebuild it locally, run `mur docs compile`.
163+
```
164+
165+
## 8. Out of Scope
166+
167+
- **CI-based doc regeneration.** Spec 013 describes a CI check that verifies committed `guide/` matches a fresh compile. Wiring that up (probably via a self-hosted Windows runner with WinAppDriver) is a separate effort tracked independently.
168+
- **Gitignoring `guide/`.** Keeping compiled output committed is a deliberate choice tied to the CI constraint above. Revisit only after CI-based regeneration lands.
169+
- **Renaming `reference/`.** The existing name matches convention and contents; no reason to disturb it.
170+
- **Splitting `guide/` into sub-sections** (tutorials vs. how-to vs. concepts, Diátaxis-style). Worth considering, but not this spec — move first, categorize later.
171+
172+
## 9. Execution Plan
173+
174+
Tracked in `docs/specs/tasks/docs-reorganization-implementation.md` (to be written when execution starts). Sketch:
175+
176+
1. Create target directories.
177+
2. `git mv` all paths per Section 3 in a single commit.
178+
3. Update pipeline code references per Section 5 in a second commit.
179+
4. Update `README.md` links and create `docs/README.md` per Sections 6–7 in a third commit.
180+
5. Run `mur docs compile` locally to verify the pipeline still produces byte-identical output under the new path.
181+
6. Run `dotnet build Reactor.sln` and full test pass.
182+
183+
Three commits keep review tractable: a pure rename, a code update, a docs update.
184+
185+
## 10. Open Questions
186+
187+
- Should `_pipeline/` move to top-level `tools/doc-pipeline/` instead? Leaning no — keeps apps + templates + output visually paired.
188+
- Should `pitch/` live under `docs/` at all, or move to a top-level `branding/` folder? Current call: keep in `docs/` since the pitch doc links heavily to `guide/` content.
189+
- Should `reports/work-summary/` be gitignored going forward and regenerated on demand? Current call: keep committed, same reasoning as `guide/`.

0 commit comments

Comments
 (0)