ahmido
af5fa30341
Implements website feature branch `410-public-docs-ia`. Target branch: `website-dev`. Validation: - `corepack pnpm --filter @tenantatlas/website build` - Playwright smoke coverage for public routes and docs interactions - Static claim scans for `apps/website/src`, `apps/website/public`, and `apps/website/dist` Follow-up integration path after merge: `website-dev` -> `dev`. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #412
96 lines
6.8 KiB
Markdown
96 lines
6.8 KiB
Markdown
# Research: Public Docs & Knowledge Base IA
|
|
|
|
## Decision: Use a dedicated `/docs` route family with `/en/docs/` for English
|
|
|
|
**Rationale**: The current website already ships a bilingual Starlight docs surface, but it is mounted at the site root through starter-style routes such as `/welcome-to-docs/` and `/guides/*`. The spec explicitly prefers a `/docs` family, and the repo already has the nested docs infrastructure needed to support it. Moving the docs IA under `/docs` gives the public site one clear documentation destination instead of mixing docs pages into the root route tree.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Keep `/welcome-to-docs/` and the root-mounted starter docs as the primary IA: too weak and misaligned with the spec.
|
|
- Use `/dokumentation`: possible, but it would add a second localized slug family where the current site already tolerates English technical slugs.
|
|
- Build only a single landing page: unnecessary because nested docs routes are already supported.
|
|
|
|
## Decision: Keep docs slugs stable and English across both locales
|
|
|
|
**Rationale**: The repo already has a localized slug alias system for `/evaluierung` <-> `/evaluation`, but expanding that approach to twelve docs topic slugs would add unnecessary routing and language-switcher complexity. The wider public site already uses English slugs across both locales (`/platform`, `/trust`, `/pricing`, `/contact`, `/use-cases/...`), so `/docs/getting-started/` and `/en/docs/getting-started/` are the narrowest consistent choice.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Localize every docs slug (`/dokumentation/erste-schritte/` etc.): more route aliasing, more smoke coverage, and more language-switching complexity for little user benefit.
|
|
- Keep mixed starter slugs like `/guides/*`: does not match the required IA.
|
|
|
|
## Decision: Reuse Starlight + MDX for docs pages instead of `siteCopy.ts` or custom Astro pages
|
|
|
|
**Rationale**: The current repo already validates docs content through `src/content.config.ts`, Starlight docs schema, and the website build. Starlight also already handles the docs shell, sidebar, and generated search assets. The required public docs IA is concept-heavy and page-rich, so MDX content pages are a better fit than large copy objects inside `siteCopy.ts` or a second handcrafted docs rendering system.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Store docs body content in `siteCopy.ts`: workable for nav/footer labels, but not the right shape for twelve bilingual docs pages.
|
|
- Build `/docs/*` as custom Astro marketing pages: would duplicate a docs system the repo already has.
|
|
- Create a second docs content collection: unnecessary because `src/content/docs/**` already exists.
|
|
|
|
## Decision: Replace sidebar autogeneration with explicit ordered topic entries
|
|
|
|
**Rationale**: The current sidebar is a starter mix of `guides/` autogeneration plus one manual `platform/evidence-review/` link. Spec 410 requires a fixed, user-question-based order across twelve topic pages. Explicit sidebar entries are the safest way to guarantee that order and prevent the docs IA from drifting back into guide-first starter organization.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Keep `guides/` autogeneration: too coarse and not aligned with the required category order.
|
|
- Split into many autogenerate directories: more structural churn than needed for v1.
|
|
|
|
## Decision: Preserve public continuity through legacy docs redirects or equivalent aliases
|
|
|
|
**Rationale**: The repo already exposes `/welcome-to-docs/`, `/guides/*`, and `/platform/evidence-review/` in nav/footer or smoke coverage. Dropping those routes without continuity handling would create user-facing regressions. Redirecting or aliasing those URLs to the new `/docs` family preserves continuity without keeping two parallel docs IAs alive.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Keep both old and new docs trees permanently: duplicate truth and split discoverability.
|
|
- Remove the old URLs entirely: too risky and inconsistent with the existing smoke inventory.
|
|
|
|
## Decision: Keep nav and footer link ownership in `siteCopy.ts`
|
|
|
|
**Rationale**: Navbar and footer copy already come from `apps/website/src/data_files/site-copy.ts` and use `localizeHref()` from `src/i18n.ts`. Retargeting those existing docs links from `/welcome-to-docs/` to `/docs/` is narrower than adding a second navigation configuration path.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Add a standalone docs-nav config: unnecessary while nav/footer already read from `siteCopy.ts`.
|
|
- Hardcode docs links directly in Astro components: weaker localization consistency.
|
|
|
|
## Decision: Prioritize homepage, platform, trust, evaluation, nav, and footer for guaranteed docs discovery
|
|
|
|
**Rationale**: Those surfaces are the clearest adjacent entry points named in the spec and already exist in the public route inventory. Review-packs and use-case pages can also expose docs discovery if their current section density stays readable, but the minimum guaranteed discovery set should stay focused.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Footer-only discoverability: too weak.
|
|
- Main-nav-only discoverability: not enough contextual handoff.
|
|
- Add a large docs mega-menu: too broad for the current public IA.
|
|
|
|
## Decision: Reuse existing Playwright smoke helpers and route inventories as the narrowest proof
|
|
|
|
**Rationale**: `apps/website/tests/smoke/public-routes.spec.ts`, `interaction.spec.ts`, and `smoke-helpers.ts` already validate route rendering, metadata, placeholder-link bans, nav/footer reachability, and forbidden public claims. Extending those suites is the narrowest proof path for this feature.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Manual-only browser review: insufficient for metadata and route migration regressions.
|
|
- New unit tests for MDX/frontmatter shape: weaker end-user proof than the existing route smokes.
|
|
- A second docs-specific browser suite: unnecessary duplication.
|
|
|
|
## Decision: Treat claim scans as blockers, not optional review aids
|
|
|
|
**Rationale**: The main risk in this feature is public overclaiming rather than runtime breakage. Static scans over `apps/website/src`, `apps/website/public`, and `apps/website/dist` are a cheap way to catch unsupported trust/provider/automation language, placeholder links, and leaked internal jargon.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- Code review only: too easy to miss banned phrases in metadata or generated output.
|
|
- A new custom linter: heavier than needed for one bounded website feature.
|
|
|
|
## Decision: Use only existing website commands for validation
|
|
|
|
**Rationale**: The website package already exposes `build`, `test`, `test:smoke`, and formatting scripts. The plan should rely on those real commands instead of inventing a standalone `check` script or touching root workspace contracts.
|
|
|
|
**Alternatives considered**:
|
|
|
|
- `pnpm --filter @tenantatlas/website check`: not present.
|
|
- Root script changes: out of scope.
|
|
- Platform/Sail commands: wrong layer for a website-only feature. |