2026-04-08: Documentation distribution by type and tool

2026-04-08 Accepted

Context

Groupe-3D projects generate many documentation needs: technical choices, installation procedures, team conventions, architecture, deployment, testing, and more. Without a clear rule about where to document what, information ends up either duplicated across multiple places or inaccessible due to the lack of an identified canonical location.

We have a set of tools and artifacts available: README.md, ADRs, a team codex, Linear, DEPLOY.md, C3D Test Planner, ARCHITECTURE.md, a docs/ folder, and the Constructions-3D AI Charter.

Decision

Each type of information is mapped to a single reference location. The table below is the official distribution rule for the Groupe-3D organization.

Topic	Location
Data to send or not send to AI tools	Constructions-3D AI Charter
Technologies used in the project	`README.md` (project root)
Project installation	`README.md` (project root)
External constraints and dependencies	`README.md` (project root) and `ARCHITECTURE.md`
Deployment (simple case)	`README.md` (project root)
Technology choices and their rationale	ADR (`decisions/` folder)
Project technical history	ADR (`decisions/` folder)
Deployment (complex case)	`DEPLOY.md` (project root)
Available AI tools	`codex`
Recommended AI resources	`codex`
Development workflows (from Linear ticket to PR)	`codex`
Branch and PR naming conventions	`codex`
Usage of Scalingo, Vercel, Scaleway	`codex`
List of organization projects	Linear
Project owner	Linear
Manual tests	C3D Test Planner
Project architecture, dependencies, services	`ARCHITECTURE.md` (project root)
Project-specific details	`docs/` folder (project root)

Rationale

Why not centralise everything in the README

The README is a project’s entry point, but it must remain readable and concise. Concentrating all documentation there (architecture, decisions, complex deployment, tests) would make it hard to maintain and counterproductive for onboarding.

Why split README, ARCHITECTURE.md, and DEPLOY.md

The separation follows the single-responsibility principle: the README guides quick setup, ARCHITECTURE.md documents the long-term structure of the system, and DEPLOY.md covers extended operational procedures. These artifacts serve different audiences and have different update cadences, and not all of them are necessary in every project.

Why use Linear for the project list and ownership

Linear is already the organization’s project management tool. This information lives there naturally and stays up to date, rather than in a static file that quickly drifts out of sync.

Why centralise cross-cutting practices in the codex

Team conventions (workflows, naming, AI tools, platforms) apply to all projects. Storing them in each individual repository would result in duplication and divergence. A centralised codex guarantees a single source of truth. See 2026-04-08-codex-setup for the setup decision.

Trade-offs

External constraints and dependencies appear in two places: the README for a brief mention, ARCHITECTURE.md for the full detail. Minimal coordination is needed to avoid contradictions.
This table requires contribution discipline: each piece of information must land in the right place, which may require an adjustment period for contributors used to writing everything in the README.

Consequences

A README.md is mandatory at the root of every project and must cover the topics listed above.
An ARCHITECTURE.md must be present in every project.
A DEPLOY.md is created at the project root only when the deployment is complex enough to exceed the scope of the README.
Technical decisions are tracked in the decisions/ folder as ADRs.
The codex is the reference location for all cross-cutting team practices.
Projects and their owners are managed in Linear.
Manual tests are documented in C3D Test Planner.
Project-specific content with no defined location above is placed in a docs/ folder at the project root.