First Thirty Days When the Wiki Is Fiction

For years I treated the internal wiki as the syllabus for a new role — read the architecture pages, follow the deployment guide, meet the team, and the system would gradually become legible. That worked well enough when the estate was young and the authors were still in the building. It stopped working the moment I inherited a logistics integration where the wiki showed a message bus, the repository held a modular monolith, and the only person who knew which story was true had left six months earlier.

The delivery manager asked, on my third day, how onboarding was progressing. I had read forty pages of documentation. I could not yet explain what happened to an order after the warehouse cut-off.

That gap is where this piece lives.

Wiki Fiction — when confident documentation describes something else

Practitioners sometimes call this documentation drift; in inherited estates it behaves more like fiction. The pages read with authority — diagrams, version numbers, owners listed from a reorganisation ago — while the running system has been patched around them for years. The failure is rarely malice. It is the ordinary decay of systems that outlive their authors.

There is a logical reason the wiki survives anyway. Even outdated material teaches vocabulary and intent: the names people use in standup, the acronyms in ticket titles, the boundaries the business still believes exist. Practice tells the same story on every handover I have seen — newcomers who skip the wiki struggle in meetings; newcomers who trust it blindly struggle in production.

The consequence is easy to state and costly to ignore. If you treat fiction as ground truth, your first changes encode new fiction on top of the old. The next hire inherits your mistakes along with everyone else's.

If documentation drift is new, the one-sentence version worth keeping is: the gap between what was written and what now runs, widening quietly while the pages still look finished.

A retail logistics estate illustrates the pattern without drama. The wiki described nightly stock allocation through a queue-backed worker. The repository contained a cron-driven script writing directly to a staging table, last meaningfully changed in a pull request whose description said "temporary — remove after peak season." Peak season was three years past. The queue in the diagram had never been provisioned in the environment I could reach.

What generic thirty-day playbooks assume

The standard engineering onboarding frame is reasonable on its own terms. Month one orients: environment, stakeholders, architecture overview. Month two contributes. Month three expects independence. Buddy programmes, first commit milestones, retrospectives at thirty, sixty, and ninety days — each sensible when the map matches the territory.

The fair objection is that structure still helps on messy estates. And it does — for everything that is not technical truth. Access cards, meeting rhythms, escalation paths: those benefit from a checklist. Where the playbook errs is in treating technical documentation as a prerequisite already satisfied.

Most templates also optimise for visible progress — first commit in days, first feature in weeks. On brownfield work, that metric rewards the wrong outcome. A visible change in week one that contradicts an undocumented batch window can cost more than a quiet fortnight spent tracing one revenue path. The playbook is not wrong for greenfield teams with accurate docs. It measures speed to contribution when the open question is speed to trustworthy understanding.

The Verification Stack — evidence in the order you can defend

When the wiki cannot be trusted, you need an explicit order of evidence. I call this the Verification Stack, because each layer must hold before the next one earns confidence.

Build evidence comes first. Can you compile, run, and execute the test suite? If local setup fails, the continuous integration configuration and container definitions become your ground truth — not the onboarding deck.

Runtime evidence follows one user-visible path. Pick the flow that hurts if it breaks: login, allocation, invoice export. Trace it in the repository and, where possible, in logs. Slides describe intent; a traced path describes behaviour.

Operational evidence asks what would alarm you if you held the pager tonight. Which alerts fire? Do the runbook steps resolve them? Shadowing one on-call shift transfers knowledge that architecture reviews rarely capture.

Ownership evidence closes the stack. Who last changed the module you care about? Version control history is a roster when no buddy was assigned.

When documentation and reality diverge, practitioners recover by trusting the executable system first and updating the record later. That is not cynicism about colleagues. It is the honest sequence for estates where the manual fell behind.

Return to the logistics example. The wiki claimed Redis held session state for the warehouse portal. Tracing authentication showed a user_sessions table and no Redis client on that path. Production configuration — confirmed with someone who had taken a page the previous month — matched the table. One afternoon of tracing taught more than a week of reading architecture fiction. The contradiction belonged in a log, not in a hurried wiki edit.

Four weeks — from survey to an artifact the next hire can use

Generic playbooks spread technical discovery across ninety days. On fiction, four weeks of deliberate verification produces an artifact someone else can inherit — which matters when you are the onboarding programme.

Week 1 — environment and one traced flow

Survey broadly, then trace one path deeply. Get the build working, or document precisely why it does not and what the pipeline uses instead. Read the readme and changelog for vocabulary, not verdicts. Choose one flow and follow it end-to-end: entry point, business rules, persistence, side effects. Write the trace in plain language a colleague could follow.

Do not attempt to understand every module. Depth on one revenue path beats breadth across twelve folders that will read differently once you understand the first.

Week 2 — contradiction log and landmine map

Open a Contradiction Log: two columns, wiki claims and verified behaviour. Every mismatch earns a line. Resist fixing pages in this week — corrections written before you understand the estate become tomorrow's fiction.

Build a Landmine Map beside it: if you were on-call tonight, what would hurt? Silent batch jobs without owners, indexes missing on tables the trace touched, alerts whose runbooks end in "ask Dave." The question is the same one reliability engineers use before accepting operational responsibility.

Week 3 — one safe change

Michael Feathers' legacy work begins at change points: identify an inflection point, cover it with tests, then move. Legacy here means code you cannot change safely — often code without tests, regardless of age.

Your week-three change should be revertible and instructive: a log line on the traced flow, a characterization test that locks current behaviour, a comment in the module you now own. The refactor you wish someone had done in 2019 is not a week-three target.

On the logistics estate, week three might add logging around the cut-off window the wiki mis-described — enough to prove when allocation actually runs, not enough to change it.

Week 4 — the handover you wish you had received

Ship a single page: traced flow summary, Contradiction Log highlights, Landmine Map top entries, names of people who answered specific questions. That document is more valuable than another wiki page because it is dated, verified, and explicit about gaps.

Documentation maintained as code only helps when someone reviews it against reality. You have just performed that review for month one. Structured onboarding still takes ninety days to full independence when done properly. On brownfield, ninety days to safe independence is a respectable outcome; six months of confident guessing is the expensive one.

Where this fails under ordinary pressure

No method survives every estate. Three probes worth applying before you trust the protocol.

When you cannot build locally, week one shifts to the pipeline: what continuous integration runs, which artefacts it produces, which secrets you lack. Escalate early. Pretending local setup is a personal failing wastes the month.

When pairing is the only knowledge transfer offered, accept the sessions — and still keep the Contradiction Log. Pairing transfers temperament and shortcuts; it does not scale and it goes stale when the guide rotates. Written verification outlives any single conversation.

When the organisation rewards visible commits over verified understanding, the political pressure is real. The response is to make your week-three change legible to management while keeping it small: observability, a test, a documented trace. Busyness is not the same as orientation.

Greenfield projects remain rare in mature organisations. Most delivery carries legacy weight — often overwhelmingly so. Month one is not a performance review. It is the moment you decide whether you will mistake the manual for the machine.

Most inherited estates do not need a heroic rewrite in the first thirty days. They need an honest trace, a log of contradictions, and one small proof that you can change the system without enlarging the fiction.

If you are in month one on an estate like this, which single flow would you trace first — and what would an honest Contradiction Log line say about it? I would value hearing how it went, particularly the parts that did not go to plan.