When an internal wiki contradicts the code, the code wins on what the product does, and the wiki wins on why it was built that way and how the team works. The contradiction does not have one winner. It has one winner per kind of sentence.
Many teams settle it in bulk, "the code is the truth" or "the wiki is the reference", and are wrong either way. The first erases decisions the code cannot hold. The second leaves online behavior the product no longer has.
Sorting a wiki, sentence by sentence
Take six sentences from a fictional team wiki, labeled illustrative, and ask the same question of each: what is this sentence about, and who can prove it?
| Wiki sentence (illustrative) | It is about… | Who is authoritative | How to check |
|---|---|---|---|
| "Invitations expire after 7 days." | behavior | the code | the value in the code, and the latest diff touching it |
| "Export is capped at 10,000 rows." | limit | the code | same: a constant may have moved |
| "We ruled out an external queue service to keep one component to operate." | decision | the wiki | nobody else wrote it down; date and author are enough |
| "Every migration goes through a two-person review." | team practice | the wiki | the practice, not the code |
| "The billing webhook retries three times." | behavior | the code | the webhook handler |
| "The reports module is planned to be replaced." | intent | the wiki, with a date | re-date it: intent ages fast |
The behavior and limit rows are the ones that lie. They were right the day they were written and nobody has a reason to reopen them: the product works, so the page looks right. That is the mechanism of documentation drift, applied to the document a team writes for itself.
Decision and practice rows lie differently. They do not become false, they become orphaned: nobody knows whether the decision still holds. A wiki that lost them lost the one thing the code will not give back.
The precedence rule in three questions
For any sentence that disagrees with the code, ask these three questions in order.
- Does the sentence describe a state the code can execute? A value, a limit, a sequence of calls. If so, the code wins, no discussion. A wiki that says 7 days when the code says 14 is wrong, even if it was reviewed.
- Does the sentence give a reason or a guideline? Why this choice, how we ship, who signs off. If so, the wiki wins, and the code can only contradict it indirectly (a guideline no commit follows may be dead).
- Does the sentence mix both? Split it. "Invitations expire after 7 days to limit dormant accounts" holds a behavior (check it against the code) and a reason (keep it in the wiki). The first half can go stale without the second one doing so.
The third question pays the most. Mixed sentences are the most numerous and the ones deleted whole out of caution, throwing out the reason with the value.
The objection: "a wiki exists so people don't read the code"
That is its job, and it does it as long as the behavior sentences are fresh. The trouble is that a reader cannot see a sentence's expiry date. A support colleague who reads "export is capped at 10,000 rows" does not think to check: they answer the customer.
Two habits bound the risk without asking anyone to read code. Write behavior values with the date they were read ("as of March 12"), or point to the source instead of copying it. And for onboarding pages, look at how to generate them from the codebase instead of rewriting them.
The mirror objection: "then drop the wiki, the code is enough"
The code does not say why. It shows that an external component does not exist, not that it was considered and refused. It carries a change, not the discussion before it. Architecture decisions can partly be recovered from history, which the article on ADRs derived from git covers, but the reason often stays in someone's head or on a wiki page.
Deleting the wiki deletes the archive of reasons. Keeping it as is keeps online values nobody checks. The precedence rule avoids both.
What the rule becomes when an agent also reads the wiki
An agent connected to your wiki repeats what it reads, with the same confidence as on the day it was written. It has no way to know that "7 days" became 14 last month unless it is given that. The same rule applies to it: behavior is read from the code and its changes, reasons and guidelines from the wiki.
DeployIt reads the real code, resynchronized on every push, and git history (commits and diffs) through its own MCP servers, and checks the code before asserting. Read-only, revocable at any time. A question about a value or a limit can then be settled by the state of the code rather than by an old page. DeployIt does not rewrite your wiki: it does not replace the decisions you record there. The same foundation feeds a living help center and an MCP server for agents, in early access / design partner program. To find pages already stale, see how to detect documentation drift.
Frequently asked questions
Should every wiki page be dated? Date the behavior claims above all. A fully dated page gives a false impression of freshness: one paragraph can be six months old and the rest six days.
What do you do with a page nobody can vouch for anymore? Mark it unverified rather than deleting it. Its reasons may still be worth something, and deletion cannot be undone.
Who decides when a developer and a product manager disagree? Split the question. On what the product does, the code answers. On what it should do, that is a decision, and it goes into the wiki once made.
Key takeaways
The code is authoritative on what runs, the wiki on what was decided. Sort the mixed sentences, date the values, keep the reasons.
DeployIt is free during early access; paid plans arrive in January 2027. The MCP server is in early access / design partner program, and the program is open.
Frequently asked questions
When the wiki and the code disagree, which one is true?
It depends on the kind of sentence. For what the product does (defaults, limits, behavior), the code is the truth because it is what runs. For why a decision was made and how the team works, the wiki is the truth, because the code does not carry that information.
Should you delete wiki pages that describe product behavior?
Not necessarily. Keep them if they explain a practice, but treat every behavior claim as perishable: date it, or replace it with a pointer to what the code establishes.
How do you spot wiki sentences that went stale?
Compare each behavior claim to the code changes made since the page date. A sentence about a module that changed since then is the first to re-read.
Should an AI agent read the wiki or the code?
Both, under the same precedence rule as humans. An agent that only reads the wiki repeats outdated behavior; an agent that only reads the code ignores decisions and team guidelines.
Continue reading
How do you announce an API or feature removal so nobody misses it?
A deprecation notice fails when it is read, understood, then forgotten. What it must contain, when to repeat it, and how to derive it from the code instead of writing it from memory.
Changelog, release notes, "What's new": which one do you need?
One change, three artefacts, three different texts. A worked example shows what each of a changelog, release notes and a "What's new" page keeps, drops and rewrites, and how to pick.
How do you keep developer portal content current between redesigns?
A developer portal ages page by page, not all at once. The way out: know which pages carry a fact from the code, and recompute those from the code instead of rereading them by hand.