The documentation's next wave: the code simplified use faster than the documentation simplified its story

[stephrobert]

An external audit read main from the raw files on 2026-08-28, deliberately
bypassing GitHub's page cache, and its verdict is not the one this project has
been answering.

axis
doc ↔ code fidelity	9/10	exceptionally strong
honesty about limits	9.5/10	probably this project's strongest point
maintainer documentation	9/10	rich and traceable
user documentation	6.5/10	too close to the internal logic
first user success	6/10	still too much friction
navigation	5.5/10	the mass is becoming the problem
FR/EN	6/10	good intent, visible inconsistencies

The problem is no longer missing documentation. It is nearly the opposite.
This project writes documentation as a scientific proof of how it works, and a
newcomer wants first to accomplish something.

The one-line diagnosis, and it is the sentence to keep: the code simplified use
faster than the documentation simplified its story. 0.11 shipped
feint.yaml + feint up + feint down, and the front door still teaches the
0.10 sequence.

What the audit confirms, and it is worth stating

The code → artefacts → proofs → documentation chain is real and it works.
feint docs --check rebuilds or checks coverage, route counts, the serve banner,
contract policies, prerequisites, install commands, client versions, the
confidence page, the routes reference, status and the feint.yaml reference —
and compares artefacts against the routes actually mounted, exiting 2 on drift.
docs/environment.md is generated from the internal/environment schema, so a
field added in code without a doc update fails the check. A test asserts that a
binary named in the docs is really produced by the release workflow, with the
Windows case written out. Another compares dispatched commands against --help,
because shapes once existed in code and not in help.

Keep all of that. None of what follows touches it.

The three depths the documentation does not yet have

30 seconds  →  I understand feint and run my first apply
10 minutes  →  I understand runtimes, providers, and the limits that matter
expert      →  conformance, contracts, evidence, corpus, shapes, drift, proxy,
               and the limits operation by operation

Today it goes from 30 seconds to expert in one step.

The ordered plan

priority	action	issue
P0	the README's promise cannot claim a client the emulator refuses	the matrix issue below
P0	feint up becomes the Quick Start, on a stack small enough to read	the onboarding issue below
P0	the three stale documents	#403, already open, and the audit reached it independently
P1	user commands separated from maintainer commands
P1	a docs/README.md index
P1	a simplified confidence matrix in the README
P1	limits.md: a 30-line summary above the 3450-line record
P1	the Quick Start generated per locale, FR and EN
P2	docs/ restructured into guides / reference / concepts / development
P2	incident narratives moved to design notes
P2	the provider × client × capability matrix generated
P2	executable Markdown examples checked in CI

The four findings worth quoting, because each is measured

1. The hero line contradicts the confidence page. README.md:41 says "Run
your Terraform against Scaleway, Outscale or Exoscale"; docs/confidence.md:48
says "A Terraform run against Exoscale — no, and refused rather than
half-served"; and feint up refuses iac.engine: terraform for that pack
before a process starts. This is exactly the class this project's own doc gates
exist to prevent, and none of them can see it: they check numbers, not claims.

2. The Quick Start is not copyable. feint start / eval "$(feint env scaleway)" / terraform apply — in which directory, with which main.tf, with
which provider? The Apply complete! shown underneath is not reachable from the
three lines above it. Meanwhile examples/stacks/scaleway/feint.yaml exists and
feint up consumes it directly.

3. The example stack is 625 lines — two VPCs, several networks, ACLs, groups,
a bastion, web and app tiers, an LB, a gateway, IPAM, placement groups, volumes,
snapshots, an image, an IAM SSH key, cloud-init. It is an excellent
qualification stack and a poor first example, and it is currently asked to
be both.

4. The French README carries an English Quick Start. Not an oversight — the
generator injects the same English block into both, and its comment says a
command needs no translation. True for commands; the block also contains prose:
"On your machine", "In CI, or anywhere Docker runs". The technical drift was
solved at the cost of an editorial one.

What this issue asks for, and what it does not

It does not ask for more documentation. It asks for a hierarchy, and it says
so as the audit did: stop adding user documentation until the hierarchy is
clear.

No honesty is lost anywhere below — what changes is when a reader is asked to
absorb which fact.

[stephrobert]

Closing on the count, line by line, because that is what this issue asked for: a
hierarchy, not more documentation. Every row of its own ordered plan is either
delivered or refused by the maintainer, and the refusals are as much an answer as
the deliveries.

priority	action	outcome
P0	the README's promise cannot claim a client the emulator refuses	delivered — the capability matrix, #592 in #595
P0	feint up becomes the Quick Start, on a stack small enough to read	delivered — #593 in #595, examples/quickstart/{scaleway,outscale}
P0	the three stale documents	delivered — #403 in #606
P1	user commands separated from maintainer commands	delivered — #598, 16 everyday / 10 fidelity
P1	a docs/README.md index	delivered — #598, four paths
P1	a simplified confidence matrix in the README	delivered — #598, "Is this the right tool for your test?" before ## Install, in both languages
P1	limits.md: a 30-line summary above the 3450-line record	refused by the maintainer — "la taille des fichiers de doc n'est pas un souci"
P1	the Quick Start generated per locale, FR and EN	delivered — #595, with a test that keeps an English sentence out of the French block
P2	docs/ restructured into guides / reference / concepts / development	refused, same decision
P2	incident narratives moved to design notes	refused, part of the same restructure
P2	the provider × client × capability matrix generated	delivered — #592
P2	executable Markdown examples checked in CI	delivered for the one that matters — tools/conformance/quickstart.sh runs the README's own four commands, and the resource count it prints is derived from the Terraform rather than typed beside it

What the audit's own diagnosis became

Its one-line finding was "the code simplified use faster than the documentation
simplified its story". That half is closed. The second audit, on 2026-08-28,
scored the same axes again and moved fidelity 9 → 9.7, first user success 6 → 8,
maintainer documentation 9 → 9.5 — and said the problem had moved to navigation,
which is what the index, the two command tables and the confidence signpost
answer.

What is deliberately not done, and why it is not a gap

The two refusals are a maintainer decision, taken twice and in as many words. The
argument that makes them coherent rather than convenient: mass is only a
problem when a reader is obliged to cross it. The index, the confidence page
and the two command tables mean nobody is. limits.md stays 3489 lines because
it is a register of measurements, and a register is not read front to back — it
is looked up, and it now has three doors that point into it.

One thing this wave taught that outlives it

Three of the four documentation defects fixed here were prose that restated a
state nobody re-read: a roadmap section, a confidence verdict, a repository
description. Only the first two now have an instrument
(TestTheRoadmapDoesNotRestateIssueState, TestEveryConfidenceRowCarriesItsProof),
and the third — the GitHub description, the single most-read sentence about this
project — is held by nobody. That is #599, open, and it is this wave's real
residue.