Documentation Information Architecture

Status

Normative Documentation Architecture Constitution

Purpose

This document defines the official Documentation Information Architecture of CMonChoix Platform.

The documentation is an official Platform component.

It must therefore be designed as an architecture:

• with explicit responsibilities;
• with stable navigation rules;
• with governed evolution;
• with reader-oriented entry points;
• with durable information boundaries.

This document does not define the current MkDocs configuration.

It defines the permanent rules that the documentation navigation must follow.

Why This Architecture Exists

The documentation exists to make the Platform understandable, operable, extensible and governable.

Without a deliberate information architecture, the documentation degrades into:

• a folder mirror;
• a collection of isolated Markdown files;
• duplicated explanations;
• inaccessible reference material;
• weak onboarding and unsafe operations.

The Documentation Information Architecture exists to guarantee that:

• the documentation follows the mental model of the reader;
• architectural truth is easier to find than historical detail;
• operational procedures remain reachable without polluting conceptual entry points;
• every useful document has a place;
• the documentation remains maintainable over multiple years.

Principles

Documentation First

No major Platform evolution should become official before its documentation responsibility is identified.

Documentation is not a post-processing artifact.

It is part of the Platform design.

Architecture First

The documentation navigation must reflect Platform understanding, responsibilities and boundaries.

It must never be derived mechanically from the filesystem structure.

Reader First

Navigation must optimize for reader orientation:

• where to start;
• what this document is for;
• what to read next;
• what is normative;
• what is operational;
• what is legacy.

Progressive Disclosure

The reader should move from:

1. orientation;
2. concepts;
3. responsibilities;
4. detailed references;
5. annexes and legacy context.

No section should expose deep detail before the reader has enough context to interpret it.

One Responsibility

Each document must have one primary responsibility.

A document may reference related concerns, but it must not serve simultaneously as:

• overview;
• deep reference;
• migration inventory;
• operational procedure;
• glossary;
• architectural decision.

No Duplication

A concept must have one official explanatory home.

If the same concept appears elsewhere, the other document must summarize briefly and link to the canonical page.

No Dead End

No useful document may remain inaccessible from the official documentation system.

Each document must be:

• directly reachable from navigation;
• or reachable from an index page that is itself reachable from navigation.

Navigation by Understanding

The official navigation follows understanding, not storage layout.

The first question is:

"What is the reader trying to understand now?"

Not:

"In which directory is the file stored?"

Reading Paths

New Developer

Recommended reading path:

1. index.md
2. Foundation
3. Architecture Overview
4. Platform Blueprint
5. Architecture Principles
6. Architecture Invariants
7. Domain design documents
8. Domain Core reference
9. Pipeline / Runtime / Read Services / Write Services
10. Contracts

Primary need:

• understand the Platform model;
• understand the responsibilities of each layer;
• locate the official source of truth before changing code.

Architect

Recommended reading path:

1. Architecture Overview
2. Platform Blueprint
3. Principles
4. Invariants
5. Boundary Architecture
6. Canonical Identity
7. Architecture Review Report
8. Architecture Remediation Plan
9. ADR
10. Documentation Information Architecture

Primary need:

• validate consistency;
• review boundaries;
• govern future changes;
• preserve long-term architectural coherence.

Operator

Recommended reading path:

1. Foundation
2. Operations Overview
3. CLI Overview
4. Read Services Overview
5. Operations procedures
6. Database operational references

Primary need:

• run the system safely;
• observe the system;
• validate data without mutation;
• recover from incidents.

Contributor

Recommended reading path:

1. Documentation Information Architecture
2. Documentation Constitution
3. Documentation Standards
4. Documentation Navigation V2
5. Documentation migration plan

Primary need:

• know where a new document belongs;
• avoid duplication;
• know whether to extend an index, create a section, or add an annexe;
• keep the documentation architecture stable.

Documentary Categories

Official Documentation

Official documentation defines the supported understanding path of the Platform.

Typical content:

• entry points;
• overviews;
• normative architecture pages;
• official design pages;
• stable component references.

Official documentation should appear directly in navigation.

Reference Documentation

Reference documentation provides detailed definitions for a stable topic.

Typical content:

• contracts;
• component-level reference pages;
• detailed domain references;
• database references;
• ADR pages.

Reference documentation is usually reached through an index page, not always directly from top-level navigation.

Operational Documentation

Operational documentation explains how to run, inspect, validate, recover or govern the Platform in practice.

Typical content:

• CLI pages;
• operations pages;
• read-only workflows;
• monitoring and incident procedures.

Operational documentation must be grouped by operator tasks, not by implementation detail.

Annexes

Annexes contain useful but secondary material.

Typical content:

• short bridge pages;
• compatibility notes;
• compact technical side topics;
• narrowly scoped support references.

Annexes are preserved, but they must not overload first-level navigation.

Legacy

Legacy documentation is retained because it still provides historical, transitional or audit value.

Typical content:

• generated inventories;
• placeholder pages not yet mature enough for first-class navigation;
• bridge documents kept for compatibility with historical links;
• transitional migration material.

Legacy does not mean useless.

It means:

• not yet a primary understanding path;
• subject to later review;
• intentionally separated from the official core path.

Evolution Rules

When To Create A Page

Create a page when:

• the topic has one durable responsibility;
• the topic cannot be explained safely inside an existing page without mixing responsibilities;
• the topic will likely be referenced more than once;
• the topic needs its own stable URL.

Do not create a page only because a file or directory exists in the codebase.

When To Create A Section

Create a section when:

• multiple pages share one reader intent;
• the section provides a meaningful entry point;
• the grouping improves understanding rather than exposing raw storage layout;
• the section is expected to remain stable over time.

When To Create An Index

Create an index page when:

• several related pages need orientation;
• readers need reading order;
• the section would otherwise become a dead end or a flat list;
• the group mixes overview and detailed pages.

An index page must explain:

• purpose;
• scope;
• what belongs here;
• what does not belong here;
• recommended reading order;
• related documents.

When To Create An Annexe

Create an annexe when:

• the content is useful but secondary;
• the content is too narrow for main navigation;
• the content supports a primary page without replacing it;
• the content preserves compatibility or historical context.

When To Keep A Legacy Document

Keep a legacy document when:

• it preserves audit traceability;
• it supports migration decisions;
• it is still linked or operationally useful;
• deleting it would remove context without a replacement.

When To Remove A Document

A document should be removed only when all of the following are true:

• its responsibility is obsolete or replaced;
• its useful content exists elsewhere in canonical form;
• it has no remaining navigation, reference or operational value;
• its removal does not create a dead end.

Deletion is never the first action.

The preferred order is:

1. classify;
2. replace or merge;
3. relink;
4. remove only when safe.

Invariants

The following invariants must always remain true:

The navigation follows reader understanding

The official navigation is designed from reader intent, not from directory names.

A document has one primary responsibility

If a page mixes multiple responsibilities, the architecture must be reconsidered.

No useful document is inaccessible

All useful documents must be reachable through the official documentation system.

The documentation is a strategic asset

The Platform documentation is part of the Platform architecture and governance.

Official entry points remain stable

Core orientation pages should evolve carefully and keep durable responsibilities.

Depth remains controlled

Navigation depth must remain readable.

The target maximum depth is three levels.

Legacy never defines the architecture

Historical artifacts may inform the documentation, but must not define its information architecture.

Quality Gates

Any documentation navigation proposal must satisfy all of the following:

• no inaccessible useful page;
• no duplicated primary navigation path for the same responsibility;
• maximum depth of three levels;
• explicit support for new developer, architect, operator and contributor reading paths;
• coherence with Platform architecture;
• coherence with Domain First;
• coherence with Documentation First.

Decision Rule

If a navigation choice improves discoverability but weakens responsibility boundaries, responsibility wins.

If a navigation choice preserves folder symmetry but harms reader understanding, reader understanding wins.

If a document is useful but too narrow for main navigation, it moves to reference or annexe, not to deletion.

Related Documents

• Documentation Constitution
• Documentation Standards
• Documentation Architecture Review
• Documentation Navigation V2
• Documentation Navigation Migration Plan

Future Evolution

This document may be refined as the Platform documentation grows.

Its principles and invariants must remain stable even if the navigation structure evolves.