Blog Home Kelvin Jackson

Every Software Project Is Also An Intro course

The education of new developers is an essential part of any software project, yet it is all too often neglected. Even when a project has a respectable amount of documentation available — which is not a given, unfortunately, even for professional projects — it is common for this documentation to focus on instructions for users (not necessarily constributors) and notes that the development team leaves for itself, forcing new team members to spend their first few days bushwhacking through unfamiliar code, searching for elements that look like they match the feature that they are hoping to modify.

However, it doesn't have to be (and shouldn't be) that way. Unless the project is a 5-line script that you know nobody but you will ever use (and even arguably then), you need to start preparing _now_ for the possibility that you will someday onboard a new developer — or need bring yourself back up to speed on the project in a year or two! Remember, you currently have a lot of information memorized that a person who has never seen the project will not have access to, and that you yourself are likely to forget if you stop working on the project on a daily basis.

At a minimum, an "onboarding page" should explain how to build the project and run tests, a high-level overview of the architecture, and a rundown of its major components and where their code is located. It should give a new developer everything they need to know to start contributing to the project, without overloading them with details or information that they will only need if and when they have to touch a particular small part. Ideally, it would also reduce the amount of time the new person had to spend combing through code files before they can make their first change, although some amount of detective work is probably inevitable when first getting acquainted with a codebase. Remember also that no matter how familiar a person is with your stack, they still need to be told the exact build and test commands and the environments they expect; otherwise they risk wasting hours on trial and error.

It is common for developers to rely on a wiki as the primary documentation for their project, and this is certainly better than nothing — any team member can edit it, usually without committing anything to source control, and a well-maintained wiki can be an incredibly useful information source for current developers. However, if you rely on your wiki as the sole form of internal documentation, be aware that you may be condemning new team members to several days or weeks of hopping from article to article, trying to figure out how to do basic tasks that the rest of the team has memorized. It's certainly okay for your onboarding resources to be stored as a page or two in the wiki, but it is essential that they exist, and that there is more to them than just a list of topic pages to study.

Finally, it bears repeating once again that there is no substitute for having a comprehensive suite of unit and automated integration tests that can be run with a single command. A developer unfamiliar with your product may not realize that they have introduced a bug based solely on the program's behavior, but unit tests should (hopefully) catch many of these bugs before they hit production. Get used to adding a couple of unit tests every time you add a new feature or find a bug that the tests didn't catch, and you'll quickly have a very useful debugging tool at your disposal.