Onboarding a remote engineer by showing, not telling

In an office, a new engineer absorbs an enormous amount without anyone deciding to teach it. They overhear the argument about the deploy. They watch someone next to them debug for ten minutes and pick up the tool they use. They see which questions get asked out loud and which get looked up quietly. None of it is in the onboarding document and all of it is onboarding.

Remote deletes that channel completely. What is left is exactly what someone decided to write down or say, which makes the quality of a remote onboarding entirely a function of how deliberate it is. It is also why a remote onboarding that copies the in-office one always feels thin: the in-office version was never the document.

The replacement is not more documents. It is showing: sessions where the new engineer watches real work happen, and recordings of the ones you would otherwise repeat.

Access is a ticket. Somebody adds an account, grants a role, sends an invite, and it is done. Teams that treat onboarding as an access checklist finish week one with a fully provisioned engineer who has no idea what the system does.

Context is the scarce thing, and it is specific: what this system is for, which parts are load-bearing, which parts everyone knows are bad and why nobody has fixed them, where a deploy can bite, and who to ask about what. Almost none of that is derivable from the repository, which is why reading the code alone produces an engineer who can change files and cannot change behaviour.

The instinct is to share your screen and show them how it works. Invert it: have them share, and you watch. It is slower, it is uncomfortable for both of you, and it is the single most valuable hour of the first week.

You will find out within twenty minutes which parts of the setup document are wrong, because they will fail in front of you rather than silently at 11pm. You will find out which assumptions your README makes about a machine that has been running this project for three years. And the new engineer fixes their own environment rather than watching somebody else operate a working one.

Then have them commit the corrections to the setup document as their first pull request. It is the only moment in their tenure when they will be able to see those errors clearly.

A directory-by-directory tour of a repository is the default and the least useful thing you can do with an hour. It teaches file locations, which an editor's search would have taught in ten seconds, and it teaches nothing about how anything works.

Trace a path instead. Take one real request from the moment it arrives to the moment something is written to a database and returned, through every service and queue it touches. Then trace a deploy, from a merged pull request to production. Then trace an incident: what alerts, who sees it, what they look at first.

Those three traces teach more than a week of reading, because they are the shape of the system rather than its contents — and because they are the same three traces every new hire needs, which is what makes them worth recording once.

Time zones make this decision for you more often than not, and a team that treats every piece of onboarding as a meeting will schedule the same three tours every quarter, each one slightly worse than the last as the person giving it gets bored of it.

Recording changes the economics. A tour recorded once can be watched at double speed, paused, rewatched in month three when it finally makes sense, and handed to the next hire without a calendar invite. It also has no bad days.

Everything before this is preparation. The first change a new engineer ships is where they find out what the team actually values, how much detail a review goes into, whether a question gets answered in an hour or a day, and whether the tests they were told about actually run.

Ship it small and ship it early — day three is not too soon. A first pull request in week three has had two weeks to accumulate anxiety and is usually too large to review properly, which makes the feedback both slower and vaguer.

Review it on a call the first time. Not because the change needs it, but because a first review is a context transfer wearing a review's clothes, and the new engineer learns more from watching you navigate their change than from the comments themselves.

Onboarding sessions involve logging into a lot of things while somebody watches, often somebody who has been at the company for four days. macOS covers the worst of it below the level of any app: while Secure Input is active — a password field, an unlock dialog, a terminal with Secure Keyboard Entry — applications stop receiving key events entirely, so the keyboard visualization is cleared and no keycap is drawn. A short banner reading Keyboard hidden — Secure Input appears in its place, so the session sees the overlay stand down rather than freeze. Turn off Show Status HUD under General if you would rather it showed nothing.

The rest is your judgement, and it is broader than passwords. Staging credentials in a config file, a customer's name in a support tool, an internal hostname in a terminal. ⌘⇧K turns the whole visualization off in one keystroke, and closing the window is still the more reliable move.

Nothing about the session is recorded by the overlay itself. Key events are processed on device, keystrokes and typed fragments are never persisted, and the app has no network entitlement at all — worth being able to say plainly when you ask a new employee to grant a privacy permission in their first week.