Main idea

The readability of a repository — consistent naming, explicit structure, useful comments, a workable merge request history — has long been defended by a single argument: it reduces the cost of developers' work. That is an argument internal to the technical team, and it loses every trade-off where it competes with a delivery date.

As soon as the repository serves to rebuild support documentation, a changelog or a specification, its readability determines the quality of those outputs. Obscure code does not produce obscure documentation: it produces documentation that is false, plausible and undetectable, since nobody will reread the source to check it.

Clean code then becomes a product variable. It is no longer a team comfort negotiable against schedule, it is the condition of existence of a family of artifacts meant for the customer.

Layer added by "Four Days of Vibe Coding as a Rusty PM" (2026-07-28). A second use of the repository produces the same shift, and it is more demanding: when the codebase becomes the ground on which a non-developer builds with an assistant, its readability decides what is feasible there. On a base whose internal APIs are documented, whose business concepts are legible and whose components are stable, a Product Manager composes a module or a flow out of existing bricks. On a badly framed base, the same person and the same assistant can only produce a separate object, plugged in from the outside — patchwork is then not a flaw of method, it is the only regime the ground allows.

Why it matters

It gives a Product Manager a reason, stated in their own terms, to defend a refactoring investment — until now defended only by developers, and therefore heard as a craftsman's preference.

It also sets an honest entry condition: the approach that consists in regenerating artifacts from the repository is not available everywhere. On an unreadable base, it does not degrade the result, it makes it misleading.

Nuances and limits

"Clean" has no opposable definition. A repository can be perfectly structured for a developer and stay silent on business vocabulary, which is precisely what support documentation needs.

And the requirement can backfire: making the repository a medium for generation risks getting comments written there for the machine rather than for the maintainer.

Open questions

• How do you recognize, before trying, that a codebase is readable enough for product artifacts to be regenerated from it?