Onboarding new engineers with recorded walkthroughs that stay current

The fifth time you explain how requests flow through the system, record it. The trick is recording it in a way that is still true next quarter.

By the VeoRec team · Oct 3, 2026 · 12 min read

Onboarding new engineers usually runs on the same few conversations, repeated with every hire: how the services fit together, how to get the app running locally, how deploys work, what the team expects in a pull request. Senior engineers give these talks again and again, a bit differently each time, and the new hire forgets half of it by Thursday because it arrived in one long afternoon.

Recording those walkthroughs fixes the repetition, and it lets the new hire rewatch the part they forgot. It also creates a new problem: recordings go stale silently, and a confident video of last year's deploy is worse than no video. So this is as much about upkeep as about recording. Below: which ten or so walkthroughs to make, how to record the tricky ones, and the ownership habits that keep a library honest after the person who made it moves on.

Record tours and reasons; write the reference

The Diátaxis framework splits documentation into four kinds: tutorials (learning by doing), how-to guides (steps for a task), reference (facts to look up) and explanation (the why and how things fit). It is a useful lens for deciding what to record.

The common failure is recording reference material: a 25-minute video that includes, somewhere around minute 14, the list of environment variables. Nobody will find it, and the list will change. Put facts in text, close to the code, and let videos explain.

Recordings also do not replace people. The chapter on knowledge sharing in Software Engineering at Google argues that written material and the knowledge held by experienced colleagues complement each other, and that a culture where newcomers feel safe asking questions matters as much as any document. A recording library frees senior engineers from repeating the basics so their time with a new hire goes to the questions that are actually new.

Build a core library of eight to twelve short recordings

Start with the conversations you already have with every new engineer. If you are not sure what they are, ask the last two people who joined what they asked about in their first week. The list for a typical web product team looks something like this:

Notice the lengths. Each recording covers one topic and stays under fifteen minutes. That is not for attention spans; it is for maintenance. When the deploy pipeline changes, you replace one five-minute video. If deploys were minute 32 to 38 of a one-hour "onboarding session" recording, the whole thing becomes untrustworthy. The post on how long a work video should be has more on splitting long recordings.

Two kinds of recording are usually not worth making. The first is a recorded live onboarding call: an hour of conversation with questions specific to one person, which nobody else will ever watch to the end. The second is anything that changes weekly, such as current priorities or who is working on what. Those belong in a written note or a standup, where they are expected to be temporary.

Make the setup video document the gotchas, not the commands

Local setup is the first thing a new engineer does and the most likely to go wrong. A video of someone typing commands is the least useful version of a setup guide: the commands should be in a script or the README, where they can be copied and kept in version control. If your project uses containers, a dev container definition (containers.dev) can make most of the setup reproducible.

What the video adds is everything around the commands:

• What a successful run looks like, so the new hire knows when they are done.
• Which warnings are normal and which mean something is broken.
• The two or three places where setup always fails (the database seed, a certificate, a VPN step) and what the fix looks like.
• How to check that everything works: the URL to open, the test to run, the page that should load.

Record it on a clean machine or a fresh user account, so the video shows what a new hire will actually see, not what your machine looks like after three years of tweaks. Then ask the next new hire to follow it and note every point where reality differs from the video. That list is your bug report for the setup.

Record the codebase tour by following one request

The system tour is the recording that saves the most senior time, and the easiest to do badly. The bad version opens the repository and goes through folders alphabetically. The good version follows something real through the system, so every folder appears for a reason.

1. Pick one real, ordinary request Something every engineer will touch: adding an item to a cart, saving a document, logging in. Not an edge case.
2. Start where the user starts Click the button in the app. Then open the network panel and show the request that goes out.
3. Follow it inward, one hop at a time Routing, the handler, the service layer, the database query. At each hop, open the file and say in one sentence what this layer is responsible for.
4. Name the surprises The cache that sits in an unexpected place, the queue that makes part of the work asynchronous, the legacy module that everything still calls. Say why it is like that if you know.
5. Come back out Show the response arriving and the UI updating. Then summarise the path in three sentences while the full diagram or file tree is on screen.
6. End with where to go next Point at the written architecture doc, the decision records and the next recording in the library.

Drop a chapter marker at each hop. A new engineer will come back to this recording in week three looking for "where does the cache live?", and chapters let them jump there. In VeoRec you press M while recording and name the markers afterwards; on Pro, AI chapters are generated automatically. For readable code on screen, zoom your editor a few steps before you start; how to record your IDE and terminal covers fonts, windows and resolution.

Cover systems and the way the team works, not just code

New engineers usually understand the code before they understand the operation around it. Two kinds of recordings fill that gap.

Operations: deploys, logs and alerts

Record a real deploy as it happens, including the checks before and after. Show the dashboards you look at, the log query you run most often, and what the three alerts that actually matter look like when they fire. The point is not to make the new hire an operator on day three; it is so the first time they see a red dashboard, it is not the first time they have seen the dashboard.

Process: how work moves through the team

How tickets are picked up, how branches are named, what a good pull request looks like here, who reviews what, how long reviews usually take, what "done" means. Much of this is written down somewhere, but a five-minute recording of a real ticket moving from backlog to production makes it concrete. It also shows the unwritten parts, like the fact that small pull requests get reviewed the same day and large ones sit. If reviews here often include a short video, point new hires to code review with video.

If the team records walkthroughs for its own pull requests, link two or three good examples here. They teach the review culture faster than any guideline; explaining a pull request with video describes the format.

Record each walkthrough so it works without you in the room

A walkthrough that works live can fall flat as a recording. In a room, the new hire stops you when they are lost. On video, they just drift. A few habits close that gap:

• Say the goal in the first sentence. "By the end of this you will know where a checkout request goes and which three services it touches." The viewer then knows what to listen for.
• Define every acronym once. Your team says "the BFF" and "PDS" without thinking. A new hire does not know them yet, and cannot ask the video.
• Pause where you would pause for questions. A two-second silence after an important point gives the viewer a moment to catch up; you can trim long gaps afterwards, or use a remove-silences option if your editor has one.
• Point deliberately. Move the cursor to what you are talking about and leave it there. Select the lines that matter.
• Do not fix unrelated things on camera. If you notice a bug during the tour, note it and move on. A three-minute detour into an unrelated fix confuses the viewer and dates the recording.
• End with the next step. Which recording to watch next, which doc to read, who to ask.

Before recording, write a short brief. It takes five minutes and keeps the recording to one topic. The templates below cover the brief and the line that goes in the library index.

Keep the library current with owners and triggers

A stale wiki page usually looks stale. A stale video does not; it shows the old dashboard with complete confidence. Three habits keep a recording library trustworthy:

1. Every recording has a named owner. Not "the platform team"; a person. When they change role, ownership moves with the handoff.
2. Every recording has a re-record trigger. "When the deploy pipeline changes." Put the trigger in the index next to the link, and mention it in the pull request template for changes that would trip it.
3. Every recording says its date in the first ten seconds. "This is the setup as of October." Viewers can then judge for themselves.

Re-record rather than patch. Editing a correction into the middle of an old video is fiddly, and a fresh five-minute take is usually faster. Trim the start and end, and keep the old version only if something links to it.

Search is the other half of keeping a library usable. When every recording has a transcript, you can find every video that mentions the old CI provider in seconds, which is exactly the list you need to re-record after a migration. New engineers use the same search to find the minute that answers their question. VeoRec transcribes every recording automatically and lets you search what was said across your library; here is what that looks like:

The searchable transcripts guide has more on how transcripts, captions and search work together.

A worked example: the CI migration

Say the team moves from one CI service to another over a sprint. The pull request that switches the pipeline config trips the trigger for the deploy recording, so its owner re-records that one. That is the obvious part. The less obvious part is everywhere else the old pipeline appears: the setup video mentions "the CI badge going green", the debugging walkthrough opens a failed build in the old dashboard, and the how-we-work video shows where to find test results.

Search the transcripts for the old service's name and you get that list in a minute. In this example it might be four recordings. Two need a fresh take (deploy and debugging), one needs nothing but a corrected line in the index ("test results now live under Checks"), and one mentions it in passing and can wait for its next scheduled refresh. Without the search, you would find the stale ones the way most teams do: a new hire spends an afternoon looking for a dashboard that no longer exists.

Let each new hire improve the library for the next one

The people best placed to judge onboarding material are the ones who just went through it. Everyone else has forgotten what was confusing. Build that into the process:

• Comment at the moment of confusion. Ask new hires to leave a timestamped comment wherever a recording confused them or turned out to be wrong. That is far more precise than a feedback form at the end of week two. In VeoRec, comments sit at the second they refer to, and the owner can reply in a thread and mark it resolved once the recording is fixed.
• Give them one recording to own. By the end of their first month, the new hire re-records the setup video, since they are the person who most recently did it from scratch.
• Ask the same three questions every time. What did you have to ask a person about that should have been in the library? Which recording was out of date? Which one was most useful?

Over a few hires, this turns the library from something a senior engineer made once into something the team maintains as a side effect of onboarding.

Plan the first two weeks around the library

Recordings work best as preparation for conversations, not replacements for them. Ask the new hire to watch the system tour before their first session with the tech lead; that session can then start at "what questions do you have?" instead of drawing boxes on a whiteboard.

A plan that mixes recordings, writing and people. Tick items as they happen:

Adjust the order to your team, but keep the pattern: watch, then do, then talk. A recording watched the day before the task has somewhere to land; the same recording watched in a block of six on day one mostly does not.

Start with three recordings this month

You do not need the full library before the next hire starts. Record the three that save the most repeated explanation: the system tour, local setup and deploy. Give each an owner and a re-record trigger, list them in the onboarding doc with their dates, and ask the next new engineer to comment wherever they get stuck.

If you need a screen recorder for developers for this, VeoRec records a tab, a window or the whole screen from Chrome, copies the share link when you stop, and transcribes every recording so the library is searchable. The same recordings will help again when someone leaves or changes team; the guide to developer handoff documentation covers that side.