Software Engineering Onboarding Playbook

So you’re the new kid on the block. You joined the company on feature freeze day, and every engineer is scrambling to get their stuff checked in before the cutoff. There’s a tight launch deadline coming up, and all your new team members are busy putting out fires, either their own fires, or trying not to trip over other people’s fires.

Multiply that by 10x if you’re in a startup, where proper documentation is nearly nonexistent and technical debt piling up to new heights in the name of growth.

The onboarding docs haven’t been updated in months and have gone stale. Everybody else is too busy to bother. Then what do you do?

Here’s my general game plan that you might find helpful.

Grokking the codebase

This is particularly useful if the company uses a monorepo pattern. Since, in theory, every engineer checks in code into that one repo, you can run:

git log --author <name>

to figure out a rough pattern of who makes changes to a particular area of the codebase. A good place to start is to look for your team member’s code.

git log and git blame are your friends.

This helps you answer the “who does what” question, as well as “who else might be involved for changes in a particular file”.

I’ve worked for two companies that use Phabricator’s Arcanist tool for code reviews, which does a good job of squashing git commits and embedding a template of the code diff. There’s normally a link there that also takes me to the pull request itself. I’d pull it out and sometimes snoop on the comments to get a higher level understanding /context of the design decisions made at a particular time point.

The Organizational Chart

This is an excellent resource for two main reasons: This is a bird’s eye view of who’s who and gives you a slight hint on where and what features each team owns, as well as mapping them back to each individual’s role in their particular team.

Know Your Command Line Tools

See a design doc for a particular service on a Google Doc, or a Slack thread on a certain service’s behavior and wonder if there’s code that is named similarly? Well, let’s find out!

This is where common command line tools become handy. You can always use a tool like grep to search for certain keywords/terms in a source file. For example, I can run this command at the top level directory to search for a function named somefunc recursively:

grep -r 'somefunc' *

There’s another tool called ripgrep that does a similar thing.

rg ‘somefunc'

I personally love using ripgrepripgrep since it’s faster, but either one is fine.

You can also search files with a particular name pattern like so:

find . -type f -name 'HelloWorldClass.py'

Some engineering teams keep a service like Hound running, which is essentially a code search tool that you can use on a browser.

Other

Does the engineering team maintain design documents? That’s also a good place to look for keywords that you can then search for in the codebase. Ask yourself how does it map to more concrete details in code. Any combination of block diagrams and high level description can get you up to speed before you know it.

If the company uses a communication tool like Slack, you can use its Search feature to seek discussions made about a particular system. This is one of the great benefits of having an open tool where discussions are persistent and easily discoverable. This becomes a lot harder for teams that use traditional email as part of their workflow though as conversations tend to be siloed and thus containment of the underlying knowledge.

Have a notebook (physical / digital) handy. Put together a list of things that you’re unsure of or don’t understand so you can come back to them later. I do most of my development on a Mac, so the Notes app works just fine for me.

I personally maintain a checklist of questions too (macros, weird util functions/methods/classes, common logging interfaces etc.). Append to this checklist and check off some as you learn the answers to them.

Keep a running cheatsheet to important resources that you might have to look at several times over the next few weeks. Create shortcuts to useful onboarding docs that could be used as references. Maybe a hacky workaround to get Docker to load the right volumes when setting up the container? Paste them in the cheatsheet so you won’t have to hunt them down again.

Closing Thoughts

If you can take away only one thing from this whole post, always ask:

why and how the existing implementation come to be.

Remember that tribal knowledge runs organically even in the flattest organizations which preach “incredible knowledge transfer / flow”. Seek out tribal knowledge, and be genuinely curious on knowing/understanding them fully.

If you don’t know, just ASK.

Last but not least, work on documenting things as you go. Stick them in a wiki somewhere so it’s easily searchable in the future. This is a huge value add for new team members that come after you. The simple boy scout rule goes a long way.