Onboarding when you don't have access to the team

Mitchell Hashimoto, Contributing to Complex Projects:

The first step to understanding the internals of any project is to become a user of the project. You do not have to become an expert user, but my personal graduation criteria for this step is to try to build something real using the project, even if it is small or simple.

Analog: here's a functional area. Set it up for yourself or on your localhost. Now, make a small, well-contained change.

Learn how to build the project and get a working binary (or equivalent). Don’t bother with understanding the build system, the dependencies, etc. Just cargo cult guides, websites, whatever you need to reliably and repeatedly go from source code to runnable binary on your system.

Analog: get to the point you can run the app, run (focused) tests, and see changes in the app. Then start trying to make functional changes.

To learn the internals, I like to use an approach I call “trace down, learn up.”

Analog: for your first several changes, read from the top of the call stack down as far as you can. Don't try to make changes, but do try to note all the landmarks (files) you visit and how they relate to each other. Note “side quests” to investigate later as you go.

Don’t be afraid of complexity. I think too many engineers look at stereotypically complex projects such as programming languages, browsers, databases, etc. as magic or as destined for higher-beings. I like to remember that all projects were started by other humans. If they could do it, I can do it too. And so can you.

You, too, can gain enough understanding of an eight-year-old system to work on it as though you were around when some of it was written. In fact, your effort will compound: the longer you're around, the more you will find curious code that, it turns out, you added in the first place. 😆

Adam Keys @therealadam