|
| 1 | +# Investigate: Documentation site structure and Docusaurus configuration health |
| 2 | + |
| 3 | +Whether the current Docusaurus setup and docs organization actually serve their intended audiences well, what's fragile, and what's missing — triggered by retiring a stale docs-split plan and a real anchor-link bug found earlier this session. |
| 4 | + |
| 5 | +> **IMPLEMENTATION RULES:** Before implementing this plan, read and follow: |
| 6 | +> - [WORKFLOW.md](../../WORKFLOW.md) - The implementation process |
| 7 | +> - [PLANS.md](../../PLANS.md) - Plan structure and best practices |
| 8 | +
|
| 9 | +## Status: Backlog |
| 10 | + |
| 11 | +**Goal**: A grounded, evidence-based picture of the documentation site's real structural health — not a redesign for its own sake — so any follow-up work targets genuine gaps rather than guessed ones. |
| 12 | + |
| 13 | +**Last Updated**: 2026-07-14 |
| 14 | + |
| 15 | +**Trigger**: retiring [`PLAN-onboarding-docs-split.md`](../completed/PLAN-onboarding-docs-split.md) (superseded, never built as designed) surfaced a real, still-unmet gap — no generic developer-quickstart template exists, only ollacrm's own specific page. Separately, this session found a real, live bug class: a heading-derived hash anchor (`#upgrade-2026-07-14--sovdev-logger102--self-verification-setup`) that would have silently broken the moment its heading's wording changed, with no build failure to catch it. Both prompted a broader look rather than two narrow fixes. |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Current State — checked directly, not assumed |
| 20 | + |
| 21 | +### 1. `onBrokenLinks: 'throw'` is real and working |
| 22 | + |
| 23 | +Confirmed by direct test, not just reading the config: moving `PLAN-onboarding-docs-split.md` to `completed/` during this same session broke a relative link inside it (`INVESTIGATE-developer-first-onboarding.md` no longer resolved from the new location) — `npm run build` **failed immediately** with an exact, actionable error pointing at the broken link. This is a real, already-working safety net, not a theoretical one. |
| 24 | + |
| 25 | +### 2. `onBrokenAnchors` is *not* configured — a real, confirmed gap |
| 26 | + |
| 27 | +`docusaurus.config.ts` only sets `onBrokenLinks: 'throw'`. There's no `onBrokenAnchors` setting at all, and Docusaurus's own default for it is `'warn'`, not `'throw'` — meaning a broken `#heading-anchor` fragment (a link resolving to the right *page* but the wrong *section*, or no section at all) would **not** fail the build, only print a warning easy to miss in CI output. This is exactly the class of bug found earlier this session: a link to `using/onboarding/ollacrm#upgrade-2026-07-14--sovdev-logger102--self-verification-setup` would have silently stopped working the moment that heading's text changed (which happened repeatedly during this same session's editing), with nothing forcing a fix. |
| 28 | + |
| 29 | +### 3. Sidebar is fully autogenerated, no manual curation yet |
| 30 | + |
| 31 | +`sidebars.ts` is a single `{type: 'autogenerated', dirName: '.'}` entry, with its own comment: *"Reach for a manually curated array... once the docs tree grows complex enough to need custom ordering or grouping."* Worth checking directly whether that threshold has already been passed — see finding 4. |
| 32 | + |
| 33 | +### 4. Content is heavily skewed toward internal planning history, not published documentation |
| 34 | + |
| 35 | +Direct file count under `website/docs/`: |
| 36 | + |
| 37 | +| Directory | File count | Audience | |
| 38 | +|---|---|---| |
| 39 | +| `ai-developer/` | 59 | Internal — investigation/plan history (`PLANS.md`, `WORKFLOW.md`, every `INVESTIGATE-*`/`PLAN-*`) | |
| 40 | +| `contributor/` | 20 | Contributors to sovdev-logger's own codebase | |
| 41 | +| `using/` | 10 | Consumers integrating sovdev-logger into their own systems | |
| 42 | +| `general/` | 4 | Cross-cutting philosophy/architecture | |
| 43 | + |
| 44 | +`ai-developer/` alone is larger than the other three directories combined, and it's all published to the same public site (`sovdev-logger.sovereignsky.no`) via the same autogenerated sidebar. This raises a real, unasked question: **should the planning/investigation history be part of the public-facing docs site at all**, or does it belong somewhere else (e.g. plain repo files, not built into the Docusaurus site)? Not answered by this investigation — flagged as [Q1] below. |
| 45 | + |
| 46 | +### 5. Known, carried-over gap: no generic developer-quickstart template |
| 47 | + |
| 48 | +From the retired `PLAN-onboarding-docs-split.md`: `using/onboarding/ollacrm/index.md` is the only developer-facing onboarding page that exists, and it's ollacrm-specific (package name references, `services/api` paths, etc.) — not a reusable template. The next customer after ollacrm has nothing generic to start from. |
| 49 | + |
| 50 | +### 6. Search works — confirmed, not assumed |
| 51 | + |
| 52 | +`@easyops-cn/docusaurus-search-local` is configured; `npm run build` genuinely produces `build/search-index.json` and a `build/search/` route. Not a gap. |
| 53 | + |
| 54 | +--- |
| 55 | + |
| 56 | +## Options |
| 57 | + |
| 58 | +### Option A: Fix `onBrokenAnchors` immediately, treat everything else as separate follow-up work |
| 59 | + |
| 60 | +Set `onBrokenAnchors: 'throw'` in `docusaurus.config.ts` — a one-line config change, directly closes the exact fragility class already found once. Leave the content-organization questions (Tier/audience split, `ai-developer/` publication question) for a later, separate decision. |
| 61 | + |
| 62 | +**Pros**: cheap, immediate, directly addresses a confirmed real bug class with no design work needed. |
| 63 | +**Cons**: doesn't touch the larger structural questions (content skew, missing developer template) — but those are genuinely separate, bigger decisions, not blocked by this fix. |
| 64 | + |
| 65 | +### Option B: Full site reorganization now — decide `ai-developer/`'s public status, build the generic developer template, restructure the sidebar |
| 66 | + |
| 67 | +**Pros**: addresses everything in one pass. |
| 68 | +**Cons**: bundles a small, safe config fix with much bigger, judgment-call decisions (should 59 files of internal history be public? what does a generic template even look like before a second real customer exists to design it against?) — repeats the exact mistake `INVESTIGATE-dependency-upgrade-sweep.md` already learned from (don't bundle a critical fix with open-ended design work). |
| 69 | + |
| 70 | +### Option C: Do nothing, revisit only if another anchor-link bug actually recurs |
| 71 | + |
| 72 | +**Pros**: zero effort now. |
| 73 | +**Cons**: the `onBrokenAnchors` gap is cheap to close and already proven to bite once — no real reason to wait for a second occurrence. |
| 74 | + |
| 75 | +--- |
| 76 | + |
| 77 | +## Recommendation |
| 78 | + |
| 79 | +**Option A now, everything else deferred pending real answers to the open questions below.** The `onBrokenAnchors` fix is a one-line, zero-risk config change that closes an already-proven bug class — do it immediately, doesn't need its own `PLAN-*.md`. The larger structural questions (is `ai-developer/` appropriately public? is a generic developer-quickstart template worth building speculatively, or only once a second customer actually onboards?) are genuine judgment calls, not technical fixes, and shouldn't be bundled with the cheap safety fix. |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +## Open Questions |
| 84 | + |
| 85 | +1. **[Q1]** Should `website/docs/ai-developer/*` (59 files of internal investigation/plan history) be excluded from the public Docusaurus build entirely, kept as-is (public but not prominently linked), or something in between (e.g. a `noindex` meta tag so it doesn't show up in search engines, while staying reachable by direct link)? This project's own AI-collaboration workflow depends on these docs being *somewhere* readable/linkable (cross-references between investigations are everywhere) — the question is whether "somewhere" needs to be the same public site as customer-facing docs. |
| 86 | +2. **[Q2]** Is a generic `developer-quickstart.md` template worth building now, speculatively, or only once a second real customer (after ollacrm) actually onboards — matching this project's own repeated preference for building from evidence, not anticipation (see `INVESTIGATE-developer-first-onboarding.md`'s Option D deferral for the same reasoning)? |
| 87 | +3. **[Q3]** Now that `ai-developer/` alone is 59 files, has `sidebars.ts`'s own stated threshold ("once the docs tree grows complex enough") been reached? If [Q1] answers "keep `ai-developer/` public," does it need its own manually-curated sidebar grouping (e.g. collapsing `completed/` by default, since it's historical record rather than active reference)? |
| 88 | +4. **[Q4]** Any other Docusaurus config worth auditing while in here — e.g. is `onBrokenMarkdownLinks` (a related, distinct setting for raw markdown-style links vs. resolved anchor links) also at a safe default? Not checked yet, worth a direct look before closing this investigation. |
| 89 | + |
| 90 | +## Next Steps |
| 91 | + |
| 92 | +- [ ] Implement Option A: set `onBrokenAnchors: 'throw'` in `docusaurus.config.ts`, verify with a real build that it actually catches a deliberately-broken anchor (don't just trust the config value) — small enough to execute directly, no `PLAN-*.md` needed |
| 93 | +- [ ] Maintainer answers [Q1]–[Q3] — these are genuine judgment calls this investigation can't resolve on its own |
| 94 | +- [ ] Check [Q4] directly before considering this investigation closed |
| 95 | + |
| 96 | +## Files to Modify (Option A only, for now) |
| 97 | + |
| 98 | +- `website/docusaurus.config.ts` — add `onBrokenAnchors: 'throw'` |
0 commit comments