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
20 KiB
20 KiB
Tasks: Public Docs & Knowledge Base IA
Input: Design documents from /specs/410-public-docs-ia/
Prerequisites: plan.md (required), spec.md (required), research.md, data-model.md, quickstart.md, contracts/public-docs-routes.openapi.yaml
Tests: Runtime behavior changes are in scope for apps/website, so browser smoke, route and metadata assertions, legacy-route continuity checks, and static claim scans are required.
Test Governance Checklist
- Lane assignment:
Browserinbrowser, confidenceremains the narrowest sufficient proof for this feature. - New or changed tests stay inside the existing public-website smoke family in
apps/website/tests/smoke/. - Shared helpers and fixtures stay cheap by default; no new heavy helpers, factories, or setup layers are introduced.
- Planned validation commands remain limited to
build,public-routes.spec.ts, andinteraction.spec.tsfromapps/website/package.json. - Surface test profile stays
public website, withdocument-in-featureas the escalation path recorded inspecs/410-public-docs-ia/plan.md.
Phase 1: Setup (Shared Infrastructure)
Purpose: Confirm repo contracts, current Starlight ownership, and the exact public surfaces that the docs IA may touch.
- T001 Confirm active feature scope, user stories, docs route family, and legacy URL continuity decisions in
specs/410-public-docs-ia/spec.mdandspecs/410-public-docs-ia/plan.md - T002 Verify root workspace contracts remain unchanged in
package.jsonandpnpm-workspace.yaml - T003 Verify website validation scripts and docs stack packages in
apps/website/package.jsonandapps/website/astro.config.mjs - T004 Map current docs collection, starter docs files, Starlight ownership, and existing metadata/canonical handling in
apps/website/src/content.config.ts,apps/website/src/content/docs/,apps/website/astro.config.mjs, andapps/website/src/pages/ - T005 [P] Map global docs entry-point ownership in
apps/website/src/data_files/site-copy.ts,apps/website/src/components/sections/navbar&footer/Navbar.astro,apps/website/src/components/sections/navbar&footer/FooterSection.astro, andapps/website/src/i18n.ts - T006 [P] Map current docs smoke coverage, legacy docs routes, and discovery assertions in
apps/website/tests/smoke/smoke-helpers.ts,apps/website/tests/smoke/public-routes.spec.ts, andapps/website/tests/smoke/interaction.spec.ts
Phase 2: Foundational (Blocking Prerequisites)
Purpose: Establish the shared docs base route, route inventory, and content skeleton that every story depends on.
Critical: No user story work should begin before this phase is complete.
- T007 Move the Starlight docs base route to
/docsand replace starter sidebar autogeneration with the explicit topic IA inapps/website/astro.config.mjs - T008 Create the localized docs landing and child-page scaffolds in
apps/website/src/content/docs/index.mdx,apps/website/src/content/docs/getting-started.mdx,apps/website/src/content/docs/microsoft-365-provider.mdx,apps/website/src/content/docs/permissions-data-access.mdx,apps/website/src/content/docs/data-processing-trust.mdx,apps/website/src/content/docs/policy-evidence.mdx,apps/website/src/content/docs/drift-detection.mdx,apps/website/src/content/docs/backups-versioning-recovery.mdx,apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx,apps/website/src/content/docs/review-packs-decisions.mdx,apps/website/src/content/docs/evaluation-pilot.mdx,apps/website/src/content/docs/known-limitations.mdx,apps/website/src/content/docs/faq.mdx, and matching files underapps/website/src/content/docs/en/ - T009 Add baseline docs route inventory, docs-route metadata hooks, canonical-metadata reuse coverage, and localized docs coverage in
apps/website/tests/smoke/smoke-helpers.tsandapps/website/tests/smoke/public-routes.spec.ts - T010 Configure legacy docs URL continuity for
/welcome-to-docs/,/guides/*, and/platform/evidence-review/inapps/website/astro.config.mjs - T011 Confirm the planned docs route matrix, child-page shape, and legacy alias mapping remain aligned between
specs/410-public-docs-ia/plan.mdandspecs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml
Checkpoint: Foundation is ready for story implementation.
Phase 3: User Story 1 - Evaluators Find A Coherent Docs Hub (Priority: P1) 🎯 MVP
Goal: Deliver the core docs landing experience and the first entry page so evaluators can understand the IA and begin with the right concepts.
Independent Test: Open /docs/, /en/docs/, /docs/getting-started/, and /en/docs/getting-started/, then confirm the hero, category structure, category links, and getting-started content make the docs understandable without any other page first.
Tests for User Story 1
- T012 [P] [US1] Add route title and description assertions for
/docs/,/en/docs/,/docs/getting-started/, and/en/docs/getting-started/inapps/website/tests/smoke/public-routes.spec.ts - T013 [P] [US1] Add docs landing IA, category-card, related-link, and getting-started readability assertions in
apps/website/tests/smoke/interaction.spec.ts
Implementation for User Story 1
- T014 [US1] Author the localized docs landing page content, category summaries, and related public handoffs in
apps/website/src/content/docs/index.mdxandapps/website/src/content/docs/en/index.mdx - T015 [US1] Author the localized getting-started page content in
apps/website/src/content/docs/getting-started.mdxandapps/website/src/content/docs/en/getting-started.mdx - T016 [US1] Keep the sidebar labels and docs-home category ordering aligned with the landing-page IA in
apps/website/astro.config.mjs,apps/website/src/content/docs/index.mdx, andapps/website/src/content/docs/en/index.mdx
Checkpoint: User Story 1 is independently functional and demonstrable.
Phase 4: User Story 2 - Security, Datenschutz, And Procurement Reviewers Get Bounded Answers (Priority: P1)
Goal: Explain permissions, data processing, trust context, review-pack framing, evaluation readiness, limitations, and FAQ boundaries without fake legal or product claims.
Independent Test: Open the reviewer-oriented docs pages and confirm they answer security, Datenschutz, procurement, and trust-readiness questions without overclaiming permissions, compliance, hosting, downloads, or automation.
Tests for User Story 2
- T017 [P] [US2] Add route title and description assertions for
/docs/permissions-data-access/,/docs/data-processing-trust/,/docs/review-packs-decisions/,/docs/evaluation-pilot/,/docs/known-limitations/,/docs/faq/, and English counterparts inapps/website/tests/smoke/public-routes.spec.ts - T018 [P] [US2] Add permissions, trust, evaluation, limitations, and FAQ content assertions in
apps/website/tests/smoke/interaction.spec.ts - T019 [P] [US2] Extend forbidden-claim and real-related-link coverage for reviewer docs pages in
apps/website/tests/smoke/smoke-helpers.ts
Implementation for User Story 2
- T020 [P] [US2] Author the localized permissions and data-processing pages in
apps/website/src/content/docs/permissions-data-access.mdx,apps/website/src/content/docs/data-processing-trust.mdx,apps/website/src/content/docs/en/permissions-data-access.mdx, andapps/website/src/content/docs/en/data-processing-trust.mdx - T021 [P] [US2] Author the localized review-packs and evaluation-pilot pages in
apps/website/src/content/docs/review-packs-decisions.mdx,apps/website/src/content/docs/evaluation-pilot.mdx,apps/website/src/content/docs/en/review-packs-decisions.mdx, andapps/website/src/content/docs/en/evaluation-pilot.mdx - T022 [P] [US2] Author the localized known-limitations and FAQ pages in
apps/website/src/content/docs/known-limitations.mdx,apps/website/src/content/docs/faq.mdx,apps/website/src/content/docs/en/known-limitations.mdx, andapps/website/src/content/docs/en/faq.mdx
Checkpoint: User Story 2 is independently functional and demonstrable.
Phase 5: User Story 3 - Technical Buyers Understand Provider, Evidence, Drift, And Recovery Concepts (Priority: P2)
Goal: Explain provider connection, evidence, drift, recovery context, and findings concepts in public language without leaking internal architecture or unsupported automation claims.
Independent Test: Open the technical concept pages and verify they explain practical meaning, boundaries, and related links for provider access, evidence, drift, findings, and recovery without publishing an unverified permission matrix or one-click restore promise.
Tests for User Story 3
- T023 [P] [US3] Add route title and description assertions for
/docs/microsoft-365-provider/,/docs/policy-evidence/,/docs/drift-detection/,/docs/backups-versioning-recovery/,/docs/findings-exceptions-accepted-risk/, and English counterparts inapps/website/tests/smoke/public-routes.spec.ts - T024 [P] [US3] Add provider, evidence, drift, findings, and recovery content assertions in
apps/website/tests/smoke/interaction.spec.ts - T025 [P] [US3] Extend provider-boundary, automation-overclaim, and recovery-boundary coverage for technical docs pages in
apps/website/tests/smoke/smoke-helpers.ts
Implementation for User Story 3
- T026 [P] [US3] Author the localized provider and policy-evidence pages in
apps/website/src/content/docs/microsoft-365-provider.mdx,apps/website/src/content/docs/policy-evidence.mdx,apps/website/src/content/docs/en/microsoft-365-provider.mdx, andapps/website/src/content/docs/en/policy-evidence.mdx - T027 [P] [US3] Author the localized drift and recovery pages in
apps/website/src/content/docs/drift-detection.mdx,apps/website/src/content/docs/backups-versioning-recovery.mdx,apps/website/src/content/docs/en/drift-detection.mdx, andapps/website/src/content/docs/en/backups-versioning-recovery.mdx - T028 [P] [US3] Author the localized findings and accepted-risk page in
apps/website/src/content/docs/findings-exceptions-accepted-risk.mdxandapps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx
Checkpoint: User Story 3 is independently functional and demonstrable.
Phase 6: User Story 4 - Visitors Reach Docs Through Real Information Architecture (Priority: P2)
Goal: Make the new docs IA discoverable through the current public website without broken links, placeholder links, or silent regressions in the previous starter docs URLs.
Independent Test: Reach /docs/ and selected child pages from nav, footer, homepage, platform, trust, evaluation, and any shipped review-packs or use-case crosslinks, then confirm the legacy starter docs URLs resolve intentionally.
Tests for User Story 4
- T029 [P] [US4] Extend localized docs route inventory and legacy docs URL coverage in
apps/website/tests/smoke/smoke-helpers.ts - T030 [P] [US4] Add nav, footer, homepage, platform, trust, evaluation, and legacy starter-route docs assertions in
apps/website/tests/smoke/public-routes.spec.ts - T031 [P] [US4] Add mobile navigation, keyboard reachability, click-through, and docs-entry readability assertions in
apps/website/tests/smoke/interaction.spec.ts
Implementation for User Story 4
- T032 [US4] Retarget the global docs entry points from
/welcome-to-docs/to/docs/inapps/website/src/data_files/site-copy.ts,apps/website/src/components/sections/navbar&footer/Navbar.astro, andapps/website/src/components/sections/navbar&footer/FooterSection.astro - T033 [US4] Add homepage, platform, trust, and evaluation docs discovery content in
apps/website/src/data_files/site-copy.ts,apps/website/src/components/pages/HomePage.astro,apps/website/src/components/pages/PlatformPage.astro,apps/website/src/components/pages/TrustPage.astro, andapps/website/src/components/pages/EvaluationPage.astro - T034 [US4] Add review-packs and use-case docs discovery content only when the destination route exists and the page can reuse an existing teaser or card slot without adding a new section or displacing its primary CTA in
apps/website/src/data_files/site-copy.ts,apps/website/src/components/pages/ReviewPacksPage.astro,apps/website/src/pages/use-cases/msp.astro,apps/website/src/pages/use-cases/mittelstand.astro,apps/website/src/pages/en/use-cases/msp.astro, andapps/website/src/pages/en/use-cases/mittelstand.astro - T035 [US4] Reconcile the shipped discovery surfaces, final docs route matrix, and legacy alias mappings between
specs/410-public-docs-ia/plan.mdandspecs/410-public-docs-ia/contracts/public-docs-routes.openapi.yaml
Checkpoint: User Story 4 is independently functional and demonstrable.
Phase 7: Polish & Cross-Cutting Concerns
Purpose: Run the required validation, record proof, and close out claim-boundary and scope checks.
- T036 [P] Run static forbidden-term scans on
apps/website/srcandapps/website/publicusing the command set inspecs/410-public-docs-ia/plan.md - T037 [P] If
apps/website/distis regenerated, run static forbidden-term scans onapps/website/distusing the command set inspecs/410-public-docs-ia/plan.md - T038 Run build validation via
corepack pnpm --filter @tenantatlas/website buildusingapps/website/package.json - T039 Run route smoke via
corepack pnpm --filter @tenantatlas/website test tests/smoke/public-routes.spec.tsforapps/website/tests/smoke/public-routes.spec.ts - T040 Run interaction smoke via
corepack pnpm --filter @tenantatlas/website test tests/smoke/interaction.spec.tsforapps/website/tests/smoke/interaction.spec.ts - T041 Perform desktop and mobile docs IA smoke checks for
/docs/,/en/docs/, selected child pages, nav/footer links, contextual crosslinks, and legacy starter routes, then record SC-001 through SC-006 proof notes inspecs/410-public-docs-ia/plan.md - T042 Record validation commands, the final docs route matrix, whether the implementation shipped child pages or a section-only fallback, canonical-metadata reuse status, static scan outcomes, shipped discovery surfaces, legacy alias behavior,
Smoke Coverageclose-out, andapps/platform/**scope confirmation inspecs/410-public-docs-ia/plan.mdandspecs/410-public-docs-ia/checklists/requirements.md - T043 Run quickstart validation against
specs/410-public-docs-ia/quickstart.mdand record any documentation drift inspecs/410-public-docs-ia/plan.md
Dependencies & Execution Order
Phase Dependencies
- Setup (Phase 1): No dependencies; starts immediately.
- Foundational (Phase 2): Depends on Setup completion and blocks all story work.
- User Stories (Phases 3-6): Depend on Foundational completion.
- Polish (Phase 7): Depends on all selected user stories being complete.
User Story Dependencies
- US1 (P1): Starts after Phase 2; no dependency on other stories.
- US2 (P1): Starts after Phase 2; can overlap with US1 once the docs route, sidebar, and content scaffold exist.
- US3 (P2): Starts after Phase 2; can overlap with US2 because the technical concept pages live in separate MDX files.
- US4 (P2): Depends on the docs routes and at least one implemented docs landing/topic surface from US1-US3.
Within Each User Story
- Smoke assertions should be added before or alongside implementation and must fail before final pass.
- Shared route migration and sidebar ordering complete before full page authoring begins.
- Content authoring completes before discovery-link rollout and final build/smoke validation.
Parallel Opportunities
- Setup tasks marked
[P]can run in parallel. - US2 and US3 content-authoring tasks marked
[P]can run in parallel after the foundational route move is complete. - Phase 7 scan and validation tasks marked
[P]can be split once implementation is frozen.
Parallel Example: User Story 1
Task: "Add route title and description assertions for the docs landing and getting-started routes in apps/website/tests/smoke/public-routes.spec.ts"
Task: "Add docs landing IA, category-card, related-link, and getting-started readability assertions in apps/website/tests/smoke/interaction.spec.ts"
Parallel Example: User Story 2
Task: "Add route title and description assertions for the reviewer docs pages in apps/website/tests/smoke/public-routes.spec.ts"
Task: "Add permissions, trust, evaluation, limitations, and FAQ content assertions in apps/website/tests/smoke/interaction.spec.ts"
Task: "Extend forbidden-claim and real-related-link coverage for reviewer docs pages in apps/website/tests/smoke/smoke-helpers.ts"
Task: "Author the localized permissions and data-processing pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx"
Task: "Author the localized review-packs and evaluation-pilot pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx"
Task: "Author the localized known-limitations and FAQ pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx"
Parallel Example: User Story 3
Task: "Add route title and description assertions for the technical concept docs pages in apps/website/tests/smoke/public-routes.spec.ts"
Task: "Add provider, evidence, drift, findings, and recovery content assertions in apps/website/tests/smoke/interaction.spec.ts"
Task: "Extend provider-boundary, automation-overclaim, and recovery-boundary coverage for technical docs pages in apps/website/tests/smoke/smoke-helpers.ts"
Task: "Author the localized provider and policy-evidence pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx"
Task: "Author the localized drift and recovery pages in apps/website/src/content/docs/*.mdx and apps/website/src/content/docs/en/*.mdx"
Task: "Author the localized findings and accepted-risk page in apps/website/src/content/docs/findings-exceptions-accepted-risk.mdx and apps/website/src/content/docs/en/findings-exceptions-accepted-risk.mdx"
Parallel Example: User Story 4
Task: "Extend localized docs route inventory and legacy docs URL coverage in apps/website/tests/smoke/smoke-helpers.ts"
Task: "Add nav, footer, homepage, platform, trust, evaluation, and legacy starter-route docs assertions in apps/website/tests/smoke/public-routes.spec.ts"
Task: "Add mobile navigation, keyboard reachability, click-through, and docs-entry readability assertions in apps/website/tests/smoke/interaction.spec.ts"
Implementation Strategy
MVP First (P1 Slice: User Stories 1 and 2)
- Complete Phase 1 (Setup).
- Complete Phase 2 (Foundational).
- Complete Phase 3 (US1).
- Complete Phase 4 (US2).
- Validate the P1 slice independently with route metadata, interaction smoke, and static claim scans.
- Demo or ship the first evaluator- and reviewer-facing docs slice.
Incremental Delivery
- Finish Setup plus Foundational once.
- Deliver US1 and US2 as the P1 slice, then validate them independently.
- Add US3 and validate the technical concept pages.
- Add US4 and validate discovery plus legacy-route continuity.
- Finish Phase 7 proof and close-out notes.
Parallel Team Strategy
- One implementer completes Setup plus Foundational.
- After Phase 2:
- Implementer A: US1 docs landing and getting-started
- Implementer B: US2 reviewer and trust-oriented pages
- Implementer C: US3 technical concept pages
- Fold US4 discoverability and IA integration in after the docs route family is stable.
- Run Phase 7 validation together before merge.
Notes
[P]tasks touch different files or can be completed without waiting on another incomplete task in the same phase.[US1]to[US4]labels map directly to the user stories inspec.mdfor traceability.- MVP scope is the P1 slice: User Stories 1 and 2. User Stories 3 and 4 layer on the same route family once the core docs IA is stable.