In this guide
Codebase walkthroughs are one of the most common ways teams share knowledge, and one of the most commonly wasted hours. The typical version goes like this: someone shares their screen, opens the repository, and starts scrolling through folders saying "this is where the models live, this is the API stuff, oh and this is kind of legacy, don't worry about that." Forty minutes later the audience has seen a lot of file names and remembers almost none of them.
A walkthrough works when it tells a story. Follow one real thing through the system, stop at a handful of places that matter, explain why each one is the way it is, and leave behind something people can come back to. This guide covers how to plan, script, deliver and record a walkthrough, with a template you can reuse. It works for onboarding a new hire, introducing a team to a system they are about to inherit, or preparing for a handoff when someone leaves.
Key takeaways
- Follow one real flow end to end, such as a single request or job, instead of touring the folder structure.
- Plan six to ten stops. Each stop answers one question: what happens here, and why is it built this way?
- Start with a one-slide map so the audience knows where each stop sits in the whole.
- Show real code at real paths, but only the few lines that matter at each stop.
- Keep it to 30 to 45 minutes, with questions at the end of each section.
- Leave behind a written outline with links, and a recording if it was live. Update the outline when the flow changes.
Why folder tours fail
People remember stories much better than lists. A folder tour is a list: here is models/, here is services/, here is utils/. It has no order, no cause and effect, and no reason to remember one folder over another. It also teaches the wrong thing. Folders describe where code is stored, not how the system behaves. A new engineer does not struggle because they cannot find services/; they struggle because they do not know which of the forty files in it runs when a customer clicks "Pay".
A flow-based walkthrough fixes both. The order is the order of execution, each stop leads to the next, and the audience ends with a working mental model of at least one path through the system, which they can use to explore others. This is the same technique described in tracing a request through a web app, turned into a presentation.
Step 1: Choose the flow
Pick a flow that is:
- Representative. It uses the main patterns of the codebase: the usual way of handling requests, validation, persistence, errors and side effects.
- Important. It touches code that people will actually need to change.
- Bounded. It can be followed end to end in under an hour.
Good choices are a core user action (create an order, send a message, upload a file), a scheduled job that matters (nightly billing), or an event pipeline (a webhook arriving and being processed). Avoid flows that are mostly configuration or mostly framework magic, because there is nothing to show.
If the audience is new to the whole system, pick the flow that the most code paths share. If they are inheriting a specific area, pick the most change-prone flow in that area. git log churn data is a quick way to find it, as described in code hotspots and churn analysis.
Step 2: Trace it yourself first
Before you plan the talk, trace the flow in the code and write down every file and function it passes through. You will usually find something you did not know or had wrong. Better to find it now than live.
# Find where the route is defined
git grep -n "'/orders'" -- 'src/**/*.ts'
# Find the handler and what it calls
git grep -n "createOrder" -- src/
# See recent changes along the path, to spot what is in flux
git log --oneline -10 -- src/orders/ src/billing/charge.ts
Write the trace as a list of steps with path:line anchors. This list becomes the outline of the walkthrough.
Step 3: Choose the stops
A trace might pass through twenty files. A walkthrough should stop at six to ten. Choose the places where something important or surprising happens:
- Where the flow enters the system (route, job registration, consumer).
- Where input is validated and authorization is enforced.
- Where the core business decision happens.
- Where state is written, and in what transaction.
- Where side effects happen (email, webhooks, events, third-party calls).
- Where errors are handled, retried or surfaced.
- Anywhere with a non-obvious design decision that people will be tempted to undo.
For each stop, write one sentence on what happens and one on why it is built this way. The "why" is the part that is not in the code and the part people will remember.
Step 4: Script it
A script does not mean reading from a page. It means knowing exactly what you will show and say at each stop, so you do not scroll around looking for things. A simple template:
# Walkthrough: Creating an order
Audience: engineers joining the orders team
Length: 40 minutes
Map: one slide showing web app -> orders API -> billing -> email worker
## 1. Entry: POST /orders
File: src/api/routes/orders.ts:24
What: route registers the handler and the auth middleware.
Why: all order routes require a session; admin routes use a separate router.
## 2. Validation
File: src/orders/schema.ts:8
What: request body is parsed with a zod schema.
Why: the schema is shared with the frontend, so changing it is a breaking change.
## 3. Pricing
File: src/orders/pricing.ts:41
What: computes totals, discounts and tax.
Why: tax is computed here, not in billing, because of a past rounding bug (see ADR-0012).
## 4. Persistence
File: src/orders/repository.ts:60
What: order and line items are written in one transaction.
Why: partial orders caused support issues before the transaction was added.
## 5. Charge
File: src/billing/charge.ts:19
What: calls the payment provider with an idempotency key.
Why: retries are safe because of the key; never remove it.
## 6. Side effects
File: src/orders/events.ts:12
What: emits order.created; email worker sends the receipt.
Why: emails are async so a slow email provider can't slow checkout.
## 7. Failure paths
File: src/billing/charge.ts:55
What: declined cards roll back the order; provider timeouts mark it pending.
Why: timeouts are ambiguous; a reconciliation job resolves pending orders.
Questions to prompt:
- What would you change to add a new discount type?
- What happens if the email worker is down?
Save this outline in the repository, for example at docs/walkthroughs/create-order.md, so it lives next to the code and goes through review when it changes. It is the most valuable output of the session.
Step 5: Deliver it
Open with the map
Spend the first two minutes on one simple diagram showing the major parts the flow will pass through. Point to where each stop sits. This gives the audience a frame to hang details on. Without it, every stop feels disconnected.
Show only the lines that matter
At each stop, jump directly to the anchor and highlight the few lines that matter. Increase the editor font size. Collapse unrelated functions if your editor supports it. If you need to show more than about twenty lines, you are probably explaining two things.
Narrate the why
The audience can read code. What they cannot read is the history: the incident that led to the transaction, the reason tax lives in pricing, the constraint that makes the strange retry count necessary. Spend most of your words there.
Pause between sections
After every two or three stops, stop and ask for questions. Asking a specific question works better than "any questions?" For example, "Where do you think we'd add a check for out-of-stock items?" makes people engage with what they just saw.
End with an exercise
Finish by asking the audience to predict something: what would break if a stop were removed, or where they would make a common change. It is the quickest way to see whether the mental model landed.
Step 6: Record it and keep it alive
If the walkthrough was live, record it. Recordings are useful for people who missed it and for new hires months later, but they age. Pair every recording with the written outline, and put the date and commit hash at the top of the outline so readers can tell how current it is.
git rev-parse --short HEAD
Revisit the outline when the flow changes significantly. A good trigger: if a PR touches three or more of the anchored files, the reviewer asks whether the walkthrough needs an update. That is cheaper than rerecording, and the outline is what people actually reuse.
Variations
Asynchronous walkthroughs. For distributed teams, a recorded walkthrough of 15 to 20 minutes plus the outline often works better than a live session. Ask viewers to post one question each in a thread afterward.
Paired walkthroughs. For a single new hire, have them drive while you narrate. They navigate to each anchor themselves, which builds the muscle of finding their way.
Reverse walkthroughs. After a new team member has been around for a few weeks, ask them to give the walkthrough to you. Gaps in their explanation show you where the outline or the code needs work.
Series. For a large system, run one walkthrough per major flow over several weeks. Each one should start with the same map, so the series builds a coherent picture.
A pre-session checklist
- Flow chosen: representative, important, bounded.
- Traced end to end in the current code, with anchors.
- Six to ten stops, each with a what and a why.
- One-slide map ready.
- Editor font size increased, unrelated tabs closed.
- Outline committed to the repository with date and commit hash.
- Recording set up, if live.
- Two or three prompt questions and a closing exercise prepared.
Using a generated tour
Writing the trace and the stops is the time-consuming part. Generated tours can give you a first draft. OpenVisio's Tour produces a stop-by-stop walkthrough of a repository with article, code, diagram and slides views, which you can use as a starting outline or present directly for a broad overview, then add your team's history and reasoning on top. For a specific flow, Explore helps you check the path and its neighbors before you script it. Either way, the parts only you can add are the reasons and the history, and those are what make a walkthrough worth the hour.
A memorable walkthrough follows one real path, stops where it matters, explains why, and leaves a written trail that the next person can follow without you.
