Onboarding Documentation Must-Haves

The following documentation is a bare minimum, should be colocated in a single, easy-to-navigate location, and should be given to developers on their very first day. Ideally this documentation will allow developers to ramp up as autonomously as possible to minimize the amount of impact on the rest of the engineering team. As the CTO of Zapier said, “Information should dispense automatically by design, when it’s needed.”

Environment Setup

Each dev team should have a standardized way to set up their local development environment and workflow procedures. This includes:

Recommended IDEs

Third-party software used by the company (when possible, accounts in these systems should have been created before the developer’s first day)

Where credentials for shared organization accounts can be found (these credentials should never be stored in plaintext, anywhere, ever. I suggest using a tool such as 1Password)

How to pull code from version control

Everything that’s needed to run relevant projects locally and push changes to version control

High-Level Overview of Project Architecture

Generate visuals of how all moving parts of their project(s) work together. This should include clients, servers, databases, and third-party systems with descriptions of their purpose and how data flows between them.

Resources for Languages, Frameworks, and Tools

This should be a list of technical documentation, blog posts, and tutorials that will help the developer fill in the gaps on all of the languages, frameworks, and tools they will be expected to use. Explain specifically how each tool will fit into their daily workflow. This should also include documentation on internal tools such as build scripts the developer will use.

Coding Standards and Values

This isn’t only useful for onboarding. All developers should have a set of standards and values to which they code. If this is documented outside of the context of the onboarding documentation, simply include a link to it in the onboarding documentation. This is also a good place to discuss performance goals and expectations for developers.

Technical Processes

This is where the code review, sprint planning, and issue handling processes should be documented. Include sprint length, when and how stories are created, and how stories move through their lifecycle.

Company Jargon

Think of this section as a dictionary of domain- and company-specific terms that may not be well-known to outsiders. This is one of those sections that experienced developers may have trouble comprehensively documenting since many terms and acronyms become taken for granted. Encourage the newcomer to add missing terms when they come across them.

Team Dynamics

Briefly describe how their team is laid out and who would be best to talk to for specific types of questions. Also define or link to the code of conduct and ethics the developer should adhere to.

Organizational Structures

This section should define how the company is laid out from a high level. Describe the various teams/projects, what role they play in the company, and how they’re connected. Lay out the best way for the developer to interact with these teams.

Encourage the new developer to update this documentation as they see fit! New developers often see holes in documentation that more experienced developers don’t. This gives the developer the opportunity to make an impact right away, improve the experience for future developers, and solidify what they’ve learned.

Mentorship

Mentorship is the best way for a new developer to feel connected to their team and learn quickly. It’s also a great way to give an experienced engineer the opportunity to sharpen up their leadership skills. Set up a daily meeting for the first four weeks (or longer, if necessary) between the newcomer and a designated mentor, ideally an engineer with a high amount of experience in the company, to discuss any questions and gather feedback on the quality of the onboarding documentation. It’s very important to encourage transparency and trust within the mentor/mentee relationship. Under no circumstances should the mentee be made to feel like they’re asking a dumb question or that they aren’t valuable.

One very specific tip for this process is to explicitly tell the mentee that it’s okay to ask the same question multiple times. New people are often afraid to “look dumb” because they didn’t understand or can’t remember something. They’re taking in a lot of new information! Remember that the goal is to ramp them up quickly, so it’s better for them to ask the same question multiple times than to be slowed down for fear of judgment.

Pair Programming

Set aside a block each day for the new developer to pair program with a random teammate. This ties into mentorship, but gives the developer the opportunity to form relationships with the entire team, learn the codebase, and begin contributing immediately.