docs(plan): add documentation overhaul plan
Exhaustive audit of the docs site identified 6 stale content items, 8 structural axiom violations, and 3 content gaps. This plan proposes a 4-phase approach in dependency order: Phase 1: Fix stale content (install commands, template paths, terminology) Phase 2: Structural rework (quadrant discipline, section consolidation) Phase 3: Fill content gaps (deployment guide, theming section) Phase 4: README restructure + cross-references Key decisions: - Theming added to syntax-highlighting.md (avoids sync with themes/README) - Deployment guide kept generic (suckless: no platform configs) - Tutorial templates inlined (scope economy over starter repo) - CLI and error reference deferred/cut (scope economy) - sections.md slimmed to reference-only (quadrant split) Sketch: .sketches/2026-02-11-documentation-improvements.md
This commit is contained in:
Timothy DeHerrera
114
docs/plans/documentation-overhaul.md
Normal file
114
docs/plans/documentation-overhaul.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# PLAN: Documentation Overhaul
|
||||
|
||||
## Goal
|
||||
|
||||
Bring sukr's docs site into full axiom compliance. Fix stale content (6 items), resolve structural violations (8 pages), and fill content gaps — producing a docs site that serves the Evaluate → Install → Build → Deploy → Customize user journey without misleading, dead-ending, or duplicating information.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Documentation axiom governs all output (quadrant discipline, audience declaration, scope economy)
|
||||
- sukr builds its own docs site — every change is verifiable via `sukr` build
|
||||
- Template authoring links to upstream Tera docs, not a custom tutorial
|
||||
- Developer-facing READMEs (`queries/`) are out of scope for user-facing docs site changes
|
||||
- `themes/README.md` is a targeted exception: trimmed because theming content moves to docs site
|
||||
|
||||
## Decisions
|
||||
|
||||
| Decision | Choice | Rationale |
|
||||
| :------------------------ | :------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Phase ordering | Fix stale → restructure → fill gaps → cross-refs | Stale fixes are highest risk (users get stuck). Later phases depend on earlier pages being correct first. |
|
||||
| sections.md consolidation | Slim to reference-only, move explanation to content-organization.md | Respects quadrant split: explanation lives in content-organization, reference lives in features/sections. Preserves nav entry. |
|
||||
| Theming docs | Add section to syntax-highlighting.md | Avoids creating a new theming.md that would drift from themes/README.md. Themes ARE syntax highlighting — same topic. |
|
||||
| Deployment guide approach | Generic "copy public/ to any static host" + platform links | Suckless: no embedded platform configs to maintain. |
|
||||
| Tutorial templates | Inline minimal template set in getting-started.md | Scope economy: a starter repo is a separate project to maintain. Three inline templates are sufficient. |
|
||||
| CLI reference | Defer | One flag (`-c`). configuration.md already covers it. Create when CLI surface grows. |
|
||||
| Error reference | Out of scope | Error messages should be self-explanatory. If not, that's a code fix. This isn't API documentation. |
|
||||
| Homepage rewrite | Explanation-primary with tutorial link | Homepage ≠ standard document. Allow a concise "get started" link but don't embed a full quick-start. |
|
||||
|
||||
## Risks & Assumptions
|
||||
|
||||
| Risk / Assumption | Severity | Status | Mitigation / Evidence |
|
||||
| :---------------------------------------------- | :------- | :-------- | :------------------------------------------------------------------------------------------------------------------- |
|
||||
| Deployment guide goes stale | MEDIUM | Mitigated | Keep generic — "copy public/ to any host" + links. No platform-specific configs. |
|
||||
| Theming section creates sync with themes/README | MEDIUM | Mitigated | Add to existing syntax-highlighting.md. Reference themes/README for available theme list only. |
|
||||
| Section consolidation breaks nav discovery | LOW | Mitigated | Keep sections.md as slimmed reference page. Users browsing features/ still find it. |
|
||||
| Phases 2 and 3 not fully independent | LOW | Accepted | Homepage gets a second touch in Phase 3 to add cross-links to new pages. Acknowledged, not a blocker. |
|
||||
| Quadrant discipline improves the docs | — | Validated | Worst audit pages (homepage, README) mix quadrants most. Best pages (comparison, math, mermaid) are single-quadrant. |
|
||||
| Inline tutorial templates are sufficient | — | Validated | Docs site templates are tiny: base.html=67 lines, page.html=10 lines. Minimal tutorial set is ~30 lines total. |
|
||||
|
||||
## Open Questions
|
||||
|
||||
None. All CHALLENGE questions resolved.
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
|
||||
- All committed, user-facing docs site content (`docs/content/`, `docs/templates/`, `docs/site.toml`)
|
||||
- `README.md` (GitHub-facing — restructure for quadrant discipline)
|
||||
- `themes/README.md` (targeted exception: trim since theming content moves to docs site)
|
||||
- New content: `deployment.md` (how-to), theming section in `syntax-highlighting.md`
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- `rearch.md` (untracked, not part of the codebase)
|
||||
- `queries/README.md` (developer-facing)
|
||||
- CLI reference page (deferred — one flag)
|
||||
- Error reference page (error messages should be self-explanatory)
|
||||
- Tera template tutorial (link upstream)
|
||||
- Plugin/API documentation
|
||||
|
||||
## Phases
|
||||
|
||||
1. **Phase 1: Fix Stale Content** — every factual claim matches reality
|
||||
- [ ] S1: Replace `cargo install sukr` in `_index.md` with `cargo install --path .` after clone
|
||||
- [ ] S4: Replace Step 4 dead-end in `getting-started.md` with inline minimal templates (base.html, page.html, content/default.html)
|
||||
- [ ] S5: Normalize "Sukr" → "sukr" in `architecture.md`
|
||||
- [ ] S6: Normalize `title` in `docs/site.toml`
|
||||
- [ ] S7: Fix template override path in `templates.md` (`page/special.html` → `content/special.html`)
|
||||
- [ ] S9: Update copyright in `docs/templates/base.html` (2024 → 2026, or remove if unnecessary for OSS)
|
||||
- [ ] Add "view your site" final step to `getting-started.md` with expected output
|
||||
|
||||
2. **Phase 2: Structural Rework** — every page declares one quadrant, serves one audience
|
||||
- [ ] Rewrite `_index.md` as explanation quadrant (what sukr is, why it exists, link to tutorial)
|
||||
- [ ] Slim `features/sections.md` to reference-only (section_type field, template dispatch)
|
||||
- [ ] Move explanation content from `sections.md` into `content-organization.md`
|
||||
- [ ] Add link to upstream Tera docs in `features/templates.md`
|
||||
- [ ] Add defaults column to frontmatter table in `configuration.md`
|
||||
- [ ] Add "Theming" section to `syntax-highlighting.md` (choosing/customizing themes)
|
||||
|
||||
3. **Phase 3: Fill Content Gaps** — cover Deploy and Customize stages of user journey
|
||||
- [ ] Create `docs/content/deployment.md` (how-to: generic static host deployment + platform links)
|
||||
- [ ] Update `_index.md` to cross-link to new deployment page
|
||||
- [ ] Update `getting-started.md` "Next Steps" to include deployment
|
||||
|
||||
4. **Phase 4: README + Cross-references** — README serves as focused explanation, cross-links established
|
||||
- [ ] Restructure `README.md` to explanation quadrant (what, why, how it compares)
|
||||
- [ ] Remove duplicated comparison table (link to docs site `comparison.md`)
|
||||
- [ ] Remove inline config reference (link to docs site `configuration.md`)
|
||||
- [ ] Keep security overview (short, relevant for trust evaluation)
|
||||
- [ ] Trim `themes/README.md` to attribution + structure + link to docs site (targeted exception)
|
||||
- [ ] Add cross-references between docs pages where missing
|
||||
|
||||
## Verification
|
||||
|
||||
- [ ] `cargo test` passes (no source code changes, but hygiene check)
|
||||
- [ ] Docs site builds: `cd docs && sukr` (assumes `sukr` in PATH via `cargo install --path .`)
|
||||
- [ ] `grep -ri "Sukr" docs/ README.md` returns zero results (only lowercase "sukr")
|
||||
- [ ] Built docs site: homepage no longer claims `cargo install sukr`
|
||||
- [ ] Built docs site: getting-started tutorial has working templates and completion step
|
||||
- [ ] Built docs site: deployment page exists and renders
|
||||
- [ ] Built docs site: no broken internal links
|
||||
|
||||
## Technical Debt
|
||||
|
||||
| Item | Severity | Why Introduced | Follow-Up | Resolved |
|
||||
| :--- | :------- | :------------- | :-------- | :------: |
|
||||
|
||||
## Retrospective
|
||||
|
||||
_To be filled after execution._
|
||||
|
||||
## References
|
||||
|
||||
- Sketch: `.sketches/2026-02-11-documentation-improvements.md`
|
||||
Reference in New Issue
Block a user