TenantAtlas/specs/410-public-docs-ia/research.md

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.