Onboarding

The onboarding experience is what a new engineer will remember about their first month, and the story they’ll tell friends about the company for years. Getting it right is a leverage move.

The first PR is a doc PR

The new engineer’s first task is to read the onboarding docs, follow them, and submit a PR fixing anything that was wrong, outdated, or unclear.

Two reasons:

1. The docs stay accurate. Onboarding docs rot the moment they’re written. The only way they don’t is if every new hire is expected to fix them.
2. It teaches the workflow. By the end of day two they’ve cloned the repo, made a change, opened a PR, received review, addressed feedback, and merged. They now know the shape of every feature they’ll ever ship.

This also lowers the emotional stakes of a first PR. It’s supposed to be small. It’s supposed to be documentation. Everyone’s first PR here looks like that. See code review for what they can expect once they open it.

Week-one skeleton

Day 1

• Accounts, access, laptop, IDE setup
• Team intros — one 20-minute chat with each teammate, calendared in advance
• Environment up and running from README
• First “hello world” commit on a throwaway branch

Day 2

• Read the principles doc and the architecture doc
• Shadow a code review — read the PR, read the comments, ask why
• Start the docs-improvement PR

Day 3–4

• Merge the docs PR
• Pair with someone on a real ticket — not solo yet
• Attend a design review as a spectator

End of Week 1

• 1:1 with me: what’s confusing, what’s slower than expected, what surprised you

Not a rigid template — a scaffold. If the new hire is senior and moves faster, they move faster. If they’re junior and need day 1 to take three days, that’s fine. The point is that someone is thinking about their week deliberately, not “here’s the Slack, good luck.”

What I tell them on day one

Three things:

1. Ask any question, any time. The 15-minute rule: after 15 minutes of being stuck, ask someone. Not out of politeness — out of respect for your time. Your time is expensive to the company; a colleague’s five minutes is cheaper than your two hours.
2. Assume good intent, in both directions. If a code review comment sounds harsh, read it charitably first. Same when you’re writing one.
3. The first month is for learning, not shipping. I will not evaluate your first-month output on velocity. I will evaluate it on whether you’re building the mental map you need to be productive in month two.

What I ask managers to prepare

A doc, before day one, with:

• Who the person will report to
• What their first three months look like (rough themes, not tickets)
• What “success” looks like at day 30, 60, 90
• Who their onboarding buddy is (peer, not manager)

If this doc doesn’t exist when they arrive, we’ve told them they’re an afterthought before they’ve written a line of code.