Onboarding new teammates should be fun and easy for everyone involved.
I’ve lost track of how many developers I’ve onboarded to my engineering teams. Though important, this process is very often a pain point that sucks time away from my day-to-day responsibilities.
At least, that was the case until I created the Zero-to-Deployed guide for our team. This guide has streamlined the onboarding process so that both existing and new team members can complete the necessary training and get up to speed as quickly as possible. That way, onboarding transforms from a drain on resources to a streamlined process that allows everyone to focus on their primary responsibilities in a timely fashion.
The Zero-to-Deployed Guide
The Zero-to-Deployed Guide
The Zero-to-Deployed guide walks new devs through every single, tiny step from the moment they open their laptops until the moment they deploy a feature. We write it with deep detail so that a junior developer can follow all the steps without asking for help.
We immediately saw this pay off: Our onboarding time (for us, this spans the moment new hires open their laptops until the moment they create a PR) went from one to two weeks down to two to three days. The process also involved significantly less hands-on assistance from team leads. We then broadened the guide to apply to all engineering teams across our organization, and the benefits immediately scaled.
Below, you can find a rough outline of what we include and how detailed we get. You can use this as a template to develop your own version.
Beyond The Zero-to-Deployed Guide
Before we look at the guide itself, however, we need to consider a few important ancillary documents. After all, there’s more to your codebase than just the setup. So, we include some other complementing documents with the guide itself.
Core Concepts Onboarding
The Core Concepts Onboarding document is a high-level overview of the tools in your product and the main components of the applications. The aim with this document is not to be exhaustive, but just to give the new team member enough context and guidance to be productive. For example, it might include what a fully-baked React Component usually looks like, how our app uses some crucial library, how our app interacts with other apps/services, and the main features of our application or suite of applications, to name a few items.
Rules and Guidelines
Rules and Guidelines set the practices and standards for the codebase, acting as a how-to guide for the code that we write. For example, this document details our git management strategy and merging rules, our rules around redux patterns, unit testing guidelines, code style rules, and things to look out for during code review.
These can all be compiled into one document or spread out over many smaller ones. The important thing is that the guide is easy to reference and clearly teaches your new teammates how to write code in your repository. It also helps if you can create links directly to certain content in these documents, flagged with header anchors or separate pages, so you can easily share relevant information later during code reviews.
Maintaining the Guide
Every time we onboard a new developer, we also give them the power to edit the guide. As time goes on, steps change, and it may come to contain outdated information or be missing new material. The new team member is responsible for finding the new information and updating the guide so that future developers don’t run into this same roadblock. This is usually the only time that managers are required for assistance in order to find that information, and it becomes an increasingly rare occurrence as the guide matures.
An Example Zero-to-Deployed Guide
Here’s a high-level example of our Zero-to-Deployed guide, so you can understand how it works and create one for your own team.
Note that, in our real guide, each bullet point includes detailed commands, instructions, and examples for successfully performing that step.
Dev Setup
Figuring out the best environment for developing our app usually matures with time, as we discover which tools most effectively help our development process. We can fast-forward this discovery experience for our new teammates by explicitly walking them through setting up every tool that has been making us productive for so long.
-
What logging into your computer for the first time involves
-
Step-by-step instructions for getting logged in, and what applications you need to log into
-
-
(If needed) how to request access permissions for software/environments
-
When you open your computer, install <these things>, using <these commands>
-
Homebrew, git, etc.
-
VSCode, Postman, Chrome, etc.
-
Required and recommended extensions for each app
-
-
-
Clone the repo, then install dependencies
-
Step-by-step guide for cloning, setting up git credentials, etc.
-
-
How to run the app
-
Include main flows for them to experience to validate that their application is running smoothly
-
Building a Feature
Every development team has a different process for taking a feature from ticket to merged code. Here, we set up a step-by-step walkthrough of this process and what to expect as they reach each step.
-
How to create a feature branch
-
Typical root branch, branch naming
-
-
How to test the feature
-
Unit testing, manual testing, dependency testing
-
-
How to submit a PR
-
Rules around titles, descriptions, and build pipelines
-
What to expect during code review
-
-
How QA tests your feature
-
This gives context on what kind of feedback they'll be receiving from QA
-
-
How to merge the PR
-
How to deploy
-
How to validate a deployment
Supporting Guides for our organization
Our supporting guides are our source of truth for all practices and patterns. We make these as easy to access as we can, so that links can be shared directly to the relevant content. Our developers continuously update these guides as they come across new issues or develop new patterns.
-
Resources
-
External links for training modules
-
Important links within the organization (Confluence, JIRA, etc.)
-
-
React practices (core concepts)
-
There are lots of ways to build React applications, here’s our pattern to follow
-
-
Typescript practices (core concepts)
-
Typescript is still new to a lot of people and documentation is overwhelming. We include the important parts for our applications.
-
-
Styling React components (core concepts)
-
How we use libraries and reuse component styles
-
-
Unit testing practices (core concepts)
-
What to test for, how to test for it, and the most-used methods
-
-
Redux practices (core concepts)
-
Defining our patterns around redux, and giving examples of the most common cases
-
-
Git and pull request practices
-
Rules around branch naming, PR rules, and code review guidelines
-
At Method, we design, strategize, and build all types of software for our clients. Beyond just delivering a quality product, our duty is to teach our clients practices to leave them stronger as an organization. This is one that has proved extremely successful.
