A Cabman's Map for the Codebase: Onboarding Engineers by Route and Recall
Photo: Colin Smith , CC BY-SA 2.0, via Wikimedia Commons
London's black-cab drivers are not required to memorise every street in the capital in the abstract. They are required to build a working mental map: arteries, one-way systems, stations, bridges, and the routes that connect them under pressure. The Knowledge is often described as a feat of memory, but its real lesson for engineering leaders is about route-finding. New engineers do not need a wiki that contains everything. They need the ability to navigate a codebase, ask the right question at the right moment, and recall the shape of the system when a service is failing.
At Knight-Ware Labs, we see the same pattern in UK software teams. A new starter is issued credentials, a repository, and a link to a documentation space. The checklist says they have been onboarded. Three weeks later they cannot explain how a customer request reaches the database, which queue owns retries, or why the billing service has two deployment paths. The wiki may be complete in aggregate and useless in practice.
Why a Wiki Is Not a Map
A wiki is an archive. It is organised by author, era, and incident. A mental map is organised by purpose. The difference matters when someone is on call at 02:00 and needs to trace a failed payment.
Documentation should remain, but onboarding must not confuse reading with learning. Page views are a poor proxy for competence. A new engineer can read ten pages on observability and still fail to find the dashboard that shows queue depth. Route-learning means practising the journey: from alert to dashboard, from dashboard to logs, from logs to the owning team. It means being able to say, without searching, which system is upstream and which is downstream.
Start with the Arteries
The Knowledge begins with routes rather than random side streets. Engineering onboarding should do the same. Identify the five or six critical journeys through your estate: a user signs in; an order is placed; a payment is authorised; a notification is sent; a report is generated; a support agent changes a record. For each, draw the path across services, data stores, queues, and external providers. Then walk it with the new starter.
This is not an architecture presentation. It is a guided route. The engineer should drive the keyboard while the mentor narrates only when the route forks. The aim is to make the map usable, not impressive.
Shadowing as Route Practice
Shadowing is often treated as passive observation. It should be active recall. Before an incident review or a deployment, ask the new engineer to predict what will happen next. Which service will log first? Which dashboard will move? Which dependency is most likely to time out? The prediction does not need to be correct. The correction is the lesson.
In UK teams spread across hybrid working, this requires deliberate scheduling. A shared screen and a recorded walkthrough are useful, but they are not a substitute for a live route with questions. Keep sessions short, repeated, and tied to real work.
Recall Under Gentle Pressure
The Knowledge is tested under examination conditions, but onboarding should not feel like an interrogation. Gentle pressure means low-stakes recall: a weekly ten-minute map test, a whiteboard before a change advisory meeting, or a request to explain a service to a colleague. The engineer should practise retrieving the map, not merely recognising it.
Spaced repetition helps. Revisit the same route after one day, one week, and one month. Change one variable each time: a different environment, a different alert, a different upstream team. This builds transfer, which is what on-call work demands.
A 30-60-90 Plan for UK Teams
The first thirty days should establish arteries and vocabulary. Pair the new engineer with a route guide, not a buddy who is merely available. Cover the critical journeys, the deployment path, the incident process, and the ownership model. End with a practical route test: trace a request end to end and explain the failure modes.
By sixty days, add breadth and recall. Rotate through two adjacent domains, shadow an on-call shift without taking the pager, and run a reverse walkthrough in which the new engineer teaches the map back. Review the wiki only where it disagrees with reality; fix the gaps.
By ninety days, test route-finding under realistic constraints. Give a scenario, a time limit, and access to the usual tools. Assess how they navigate, whom they ask, and whether they can explain trade-offs. Then set a development plan for the routes they still avoid.
The Knowledge works because it produces cab drivers who can take you anywhere, not because it produces people who have read about everywhere. Onboarding should aim for the same: engineers who can find their way through the system, explain the route, and remain useful when the map is incomplete.