Docs Are Part of the Contract in APC and APX
I used to treat docs like cleanup.
Code first. Fix behavior. Then, if time remained, explain what changed.
That habit works fine until a project gets enough surface area that the docs start acting like a second implementation. At that point, stale prose is not harmless. It is a bug with better grammar.
APC and APX pushed me into a different rule: docs are part of the contract. Not marketing. Not an afterthought. Contract.
That sounds obvious until you try to keep a real project honest across multiple surfaces. APC has its spec, its repo-owned context, and its compatibility layer. APX has the runtime, the CLI, the daemon, the web admin, and local state under ~/.apx/. The moment I let one surface drift from another, people and agents start learning two truths about the same system.
That is the wrong kind of flexibility.
Why I stopped seeing docs as separate work
The turning point was simple: I noticed that every time I let docs lag behind code, I was forcing future me to re-derive the same answer twice.
Once from the implementation.
Once from the text.
That is wasteful on a small repo and expensive on a growing one.
For APC/APX, the cost is worse because the audience is not just humans. Agents read these files too. If the README says one thing and the code does another, the model is not "being clever." It is being misled by my own stale contract.
So I changed the default.
If a change alters user-facing behavior, I update the docs in the same pass. If a page explains a workflow, I treat that page like code that can regress. If a command exists in the README, I expect the command to work. If an article says a file lives in .apc/, it should not actually live somewhere else.
That rule sounds strict. It is. It also saves time.
The mirrored-tree rule forced the issue
One of the clearest examples is APC's documentation structure.
The APX project rules require mirrored locale trees: src/pages/en/ and src/pages/es/ must stay structurally identical and semantically equivalent. Same page, same shape, same keys in _meta.js, locale-matched internal links.
That is not extra ceremony. It is a built-in drift detector.
If I add a page in English and forget the Spanish version, the build should complain. If I rename a section in one locale and leave the other behind, that mismatch is not a translation issue only. It is a contract break.
This changed how I think about documentation work.
Before, I thought of translation as a late-stage pass.
Now, I think of mirrored docs as a design constraint.
The constraint is useful because it makes the system honest. I cannot accidentally say, "the docs are updated," when only one audience got the change. I have to keep both views aligned, which is exactly what a project that talks to tools should demand.
Build output is not just packaging
I also stopped treating the build as a deployment chore.
A build is where drift gets caught early.
For APC, the rule is explicit: run npm run build before calling a docs task done. For APX docs, the same idea appears in a different shape: build the docs site and verify both locale trees render. That is not overhead. That is verification that the contract still compiles.
I like that framing because it keeps docs in the same mental bucket as code:
- source changes happen in the repo
- projections are rendered from that source
- the build checks whether the projection still matches
That is the same logic I use elsewhere in the project.
APC is the repo-owned contract.
APX is the runtime that consumes it.
The rendered docs site is another projection.
If any projection starts inventing its own truth, the system gets harder to trust.
The real bug is not stale prose
The real bug is mismatched behavior.
A stale README can teach someone the wrong command.
A stale locale page can hide a feature from half the audience.
A stale spec can make an agent infer the wrong boundary between project state and runtime state.
In APC and APX, these mistakes matter more because the whole point of the project is to make boundaries obvious:
- project vs. runtime
- repo truth vs. local truth
- contract vs. execution
- source vs. projection
If docs blur those lines, they are not documenting the system. They are undoing it.
That is why I now write docs with the same question I use for code: what is the actual source of truth here?
If I cannot answer that clearly, I should not publish the sentence yet.
What changed in my workflow
The practical effect is boring, which is exactly why it works.
Now, when I touch APC or APX, I ask three things right away:
- Did behavior change, or only implementation details?
- If behavior changed, which docs need the same change now?
- Does the build prove the docs still match the repo?
That keeps me from doing the usual "fix later" move that creates drift.
It also makes writing easier. I no longer try to write a polished explanation after the fact. I write the explanation while the change is still fresh, when I can still name the tradeoff that mattered.
That matters in a project like APX because a lot of the value is in decisions, not just features.
Why does ~/.apx/ exist? Because runtime state should stay local.
Why does AGENTS.md matter? Because tool-agnostic context needs one shared contract.
Why does the web admin exist? Because it is a window into the same runtime, not a separate product.
Those are not slogans. They are design decisions. Docs should preserve that exact shape.
The rule I keep now
My rule is simple:
If a sentence describes how APC or APX works, that sentence is part of the product.
That means I have to maintain it with the same care I give code.
Not because prose is sacred.
Not because docs are pretty.
Because the project only stays coherent if every surface tells the same story.
And once I started treating docs that way, APC and APX got easier to reason about.
Less drift.
Less rework.
Fewer fake truths.
That is the whole win.
Top comments (1)
I appreciate how you've highlighted the importance of treating docs as part of the contract in APC and APX, and how this mindset shift has improved your development workflow. The mirrored-tree rule, in particular, stands out as a clever way to detect drift between different locales and ensure that documentation remains consistent. I've had similar experiences where keeping docs up-to-date has prevented downstream issues, and I'm curious - have you considered automating any part of the doc update process, such as using tools like automated documentation generators or linters to help enforce the contract?