Aller au contenu

Documentation Navigation Migration Plan

Status

Proposed Documentation Navigation Migration Plan

Purpose

This document defines how the current documentation navigation should evolve toward the target Documentation Information Architecture.

It does not modify mkdocs.yml.

It identifies:

  • current state;
  • target state;
  • impacted files;
  • priority;
  • risks;
  • migration order.

Migration Strategy

The migration must be progressive.

The goal is not to expose every existing page immediately.

The goal is to:

  1. stabilize official entry points;
  2. expose the most useful references;
  3. route secondary material through indexes and annexes;
  4. preserve legacy context without polluting the core reader journey.

Migration Order

Phase 1 — Stabilize Core Entry Points

Focus:

  • Start Here;
  • Governance;
  • Architecture;
  • Target Design.

Phase 2 — Expose Core References

Focus:

  • Domain Core;
  • Contracts;
  • Vertical Modules mature pages;
  • Business Domains Catalog.

Phase 3 — Expose Runtime And Operations

Focus:

  • Read Services;
  • Pipeline;
  • Runtime;
  • CLI;
  • Database;
  • Operations.

Phase 4 — Consolidate Migration, ADR And Annexes

Focus:

  • ADR normalization;
  • migration references;
  • stub and legacy segregation.

Section Migration Plan

1. Start Here

Current state:

  • onboarding is fragmented across index.md, foundation/, architecture/overview.md and glossary/;
  • no single explicit newcomer path exists.

Target state:

  • one official orientation section with Foundation, Architecture Overview, FAQ and Glossary.

Files concerned:

  • docs/index.md
  • docs/foundation/index.md
  • docs/foundation/platform-foundation.md
  • docs/architecture/overview.md
  • docs/architecture/faq.md
  • docs/glossary/index.md
  • docs/glossary/canonical-identity.md
  • docs/glossary/projection.md
  • docs/glossary/resolver.md

Impact:

  • strong improvement for onboarding;
  • lower risk of reader disorientation;
  • better entry path for all profiles.

Priority:

  • high

Risks:

  • weak glossary pages may remain very short;
  • overview pages may need enrichment later, but can already serve as stable entry points.

2. Governance

Current state:

  • governance pages exist and are partly visible;
  • documentary governance is still spread between governance and architecture decisions.

Target state:

  • governance becomes the explicit home for documentary rules, standards and roadmap;
  • architecture hosts the documentation architecture, not all governance rules.

Files concerned:

  • docs/governance.md
  • docs/governance/index.md
  • docs/governance/constitution.md
  • docs/governance/documentation-standards.md
  • docs/governance/documentation-roadmap.md
  • docs/governance/documentation-architecture-review.md
  • docs/governance/namespace-convergence-plan.md
  • docs/governance/repository-classification.md

Impact:

  • cleaner governance boundaries;
  • better contributor orientation;
  • easier long-term maintenance.

Priority:

  • high

Risks:

  • constitution and standards remain draft-level and may need later completion.

3. Architecture

Current state:

  • architecture already has strong core documents;
  • review and remediation pages exist but are not explicitly structured as a coherent review area;
  • documentation architecture does not yet exist as a first-class topic.

Target state:

  • architecture remains the normative conceptual path;
  • review and remediation become explicit;
  • documentation architecture becomes an official architecture topic.

Files concerned:

  • docs/architecture/overview.md
  • docs/architecture/blueprint.md
  • docs/architecture/vision.md
  • docs/architecture/principes.md
  • docs/architecture/invariants.md
  • docs/architecture/dependances.md
  • docs/architecture/boundary-architecture.md
  • docs/architecture/identifier-first.md
  • docs/architecture/canonical-identity.md
  • docs/architecture/component-map.md
  • docs/architecture/roadmap.md
  • docs/architecture/platform/index.md
  • docs/architecture/platform/reference.md
  • docs/architecture/architecture-review-report.md
  • docs/architecture/architecture-remediation-plan.md
  • docs/architecture/governance/industrial-quality-gates.md
  • docs/architecture/documentation-information-architecture.md
  • docs/architecture/documentation-navigation-v2.md
  • docs/architecture/documentation-navigation-migration-plan.md

Impact:

  • strong coherence between Platform Architecture and Documentation First;
  • better support for architects and contributors.

Priority:

  • high

Risks:

  • identifier-first.md / dependances.md duplication issue remains a known content risk outside the navigation scope.

4. Business Domains

Current state:

  • Product domain is already represented in navigation;
  • Catalog domain exists but is invisible.

Target state:

  • Business Domains becomes the official business understanding area;
  • Product and Catalog both become visible.

Files concerned:

  • all current docs/business-domains/product/*.md already in navigation;
  • docs/business-domains/catalog/index.md
  • docs/business-domains/catalog/projection-engine.md
  • docs/business-domains/catalog/runtime-sync-layer.md

Impact:

  • stronger Domain First coherence;
  • better explanation of the read-oriented Catalog capability.

Priority:

  • high

Risks:

  • bilingual content differences may later require harmonization, but not before navigation adoption.

5. Target Design

Current state:

  • design/ contains mature target component documents;
  • only the generic rules pages are visible today;
  • core component design pages are hidden.

Target state:

  • design/ becomes the official target design section for major components.

Files concerned:

  • docs/design/design-guidelines.md
  • docs/design/design-principles.md
  • docs/design/template.md
  • docs/design/domain-core.md
  • docs/design/vertical-modules.md
  • docs/design/read-services.md
  • docs/design/write-services.md
  • docs/design/pipeline.md
  • docs/design/runtime.md
  • docs/design/infrastructure.md
  • docs/design/interfaces.md
  • docs/design/governance.md
  • docs/design/frontend.md

Impact:

  • major gain in architectural readability;
  • clear separation between target design and current reference.

Priority:

  • high

Risks:

  • some readers may confuse target design with current implementation if overview pages remain too weak.

6. Platform References

Current state:

  • detailed references exist across domain-core/, contracts/, domain-engine/, vertical-modules/;
  • these references are partly invisible.

Target state:

  • one explicit reference area reached after orientation and design understanding.

Files concerned:

  • docs/domain-core/*.md
  • docs/contracts/*.md
  • docs/domain-engine/*.md
  • docs/architecture/engines/identity-engine.md
  • selected docs/vertical-modules/*.md

Impact:

  • cleaner separation between orientation and detailed reference;
  • much easier developer lookup path.

Priority:

  • high

Risks:

  • if too many references are promoted at once, the section may become dense;
  • keep only mature vertical pages here in the first pass.

7. Runtime And Operations

Current state:

  • runtime, pipeline, read-services, database, CLI and operations material is distributed across many directories;
  • some sections are visible only through isolated overview pages;
  • many valuable operational pages are hidden.

Target state:

  • one task-oriented section that supports runtime understanding, read-only validation, operations, CLI and data persistence.

Files concerned:

  • docs/application-engine/overview.md
  • docs/pipeline/*.md
  • docs/runtime/*.md
  • docs/read-services/*.md
  • docs/write-services/overview.md
  • docs/frontend/overview.md
  • docs/frontend/projections.md
  • docs/adapters/*.md
  • docs/cli/*.md
  • docs/database/*.md
  • docs/operations/*.md

Impact:

  • very large improvement for operators and developers;
  • turns currently hidden operational knowledge into an organized path.

Priority:

  • high

Risks:

  • some pages are still stubs;
  • section needs careful curation so that mature references are not mixed with immature placeholders.

8. Migration

Current state:

  • migration already exists in navigation, but some useful pages remain hidden;
  • generated and audit-heavy material is mixed with strategic migration guidance.

Target state:

  • migration stays visible as a transition area;
  • strategic migration documents are primary;
  • generated inventory remains available but clearly secondary.

Files concerned:

  • docs/migration/overview.md
  • docs/migration/methodology.md
  • docs/migration/migration-plan.md
  • docs/migration/component-classification.md
  • docs/migration/repository-cleanup-phase-1.md
  • docs/migration/architecture-atlas.md
  • docs/migration/legacy-plugin-inventory.md

Impact:

  • clearer migration governance;
  • preserves historical audit value.

Priority:

  • medium

Risks:

  • generated inventory may look canonical if not clearly positioned as legacy support material.

9. ADR

Current state:

  • ADR are split across docs/adr/ and docs/architecture/adr/;
  • location ambiguity is already a documented review finding.

Target state:

  • one visible ADR section with a stable official reading path;
  • historical split remains technically preserved until a later consolidation decision.

Files concerned:

  • docs/adr/index.md
  • docs/adr/0001-identifier-first.md
  • docs/adr/0002-domain-core-independent.md
  • docs/adr/0003-readonly-before-runtime.md
  • docs/architecture/adr/adr-004-identity-domain-service.md
  • docs/architecture/adr/adr-005-conflict-policy-extraction.md
  • docs/architecture/adr/adr-006-domain-without-wordpress.md

Impact:

  • better decision traceability;
  • easier architecture review workflow.

Priority:

  • medium

Risks:

  • ADR split remains a structural smell until the official ADR location is normalized.

10. Annexes

Current state:

  • stubs, bridge pages and narrow references exist without a clear official status;
  • they are either hidden or mixed with first-class material.

Target state:

  • annexes become a deliberate preservation zone for useful but secondary documents.

Files concerned:

  • docs/knowledge/architecture.md
  • docs/frontend/seo.md
  • docs/frontend/performance.md
  • docs/cli/feed-sync.md
  • docs/cli/rebuild-navigation.md
  • docs/cli/rebuild-projections.md
  • docs/write-services/backfill.md
  • docs/write-services/cleanup.md
  • docs/write-services/migration.md
  • docs/write-services/reclassification.md
  • docs/write-services/repair.md
  • docs/vertical-modules/gaming.md
  • docs/vertical-modules/gpu.md
  • docs/vertical-modules/mobility.md
  • docs/vertical-modules/printer.md
  • docs/vertical-modules/toys.md
  • docs/vertical-modules/tv.md
  • docs/vertical-modules/wellness.md

Impact:

  • preserves useful content without overloading the core path;
  • prevents dead ends while avoiding premature promotion.

Priority:

  • medium

Risks:

  • annexes can become a dumping ground if not governed;
  • later review remains necessary for stub maturation or archival decisions.

Cross-Cutting Risks

Risk:

  • the same concept may appear in Architecture, Target Design and Platform References.

Mitigation:

  • Architecture explains why;
  • Target Design explains target responsibilities;
  • Platform References explain detailed stable definitions.

Weak Overview Risk

Risk:

  • some overview pages are still too small to act as ideal entry points.

Mitigation:

  • keep them as entry points initially;
  • enrich later without changing the navigation architecture.

Stub Promotion Risk

Risk:

  • short pages may look more mature than they are if exposed too early.

Mitigation:

  • keep stubs in Annexes or secondary reference slots until enriched.

Historical Boundary Risk

Risk:

  • WordPress/plugin context may re-enter the main understanding path.

Mitigation:

  • keep Platform-first sections dominant;
  • isolate plugin-historical context in migration or annexes.

Validation Gates

The migration plan is acceptable only if the target navigation satisfies all of the following:

  • no inaccessible useful page;
  • no duplicated primary responsibility in navigation;
  • maximum depth of three levels;
  • explicit support for newcomer, developer, architect, operator and contributor paths;
  • coherence with Platform Blueprint;
  • coherence with Domain First;
  • coherence with Documentation First.

Future Evolution

This plan may evolve as pages become stronger, weaker, merged or replaced.

Its migration logic should remain stable:

  • orient first;
  • expose mature references second;
  • preserve annexes deliberately;
  • treat legacy as governed context, not as hidden debt.