Onboarding new developers

The Checklist

You should have an onboarding checklist of all the tasks that need to be done for new devs.

For example:

  * send welcome email
  * schedule lunch with team on first day
  * prepare second task

  * laptop
  * monitor
  * dongles

  * email login
  * slack login
  * JIRA login
  * github access
  * CI access

  * weekly planning meeting
  * communication
  * WFH days

First Tasks
  * explain first PR
  * approve their first PR
  * merge their first PR
  * first release

This checklist can live in a repository that is updated as new hires come on and as it needs to be updated. I like to keep a “team” repository to hold documents for the team.

The First Task

For me, the intention of a first task is to get the new hire acquainted with how a task travels from inception to completion. This should give them an idea of what the workflow looks like at a high level. It should touch on everything and everyone they’ll generally interact with when working through a task.

More precisely, it looks like:

Setup project
  * (link to code repository)

Your First PR
  1. Create feature branch 
  2. Update README: add your name to the TEAM section
  3. Run all tests
  4. Open Pull Request (PR)
  5. Ensure tests pass on CI
  6. Request review of PR and get approval

Release Beta Build
  * (point to doc)

Mark ticket complete
  * (describe how your team closes tickets)

This whole list can also live in the “team” repository so the new hire can open PRs against the list in case there are errors.


In the primary repository that the team works in on a day to day basis, you should keep a README that can easily be updated and quick to reference/see for new devs on the team.

As new developers get their environment setup, if they find something is broken in this doc: great! They now have the opportunity to make changes to the source and be a part of the conversation happening in the repository.

The Second Task

At this point, the new dev should have her dev environment setup and have completed a task/ticket, run tests, and released a beta build. Great! She now has an idea of what your workflow looks like.

The next task should be:

  • Discrete and isolated from your critical path
  • Able to be completed within a single week (or sprint)
  • Be related to code that has good test coverage

The last bit is important, as it serves as documentation that she can use to understand the intention of previous developers.

If she hasn’t been pair programming with the team up to now, I think it’s extremely important at this point to have someone pair with her to have a partner in diving into what she sees in her journey into the code.

Team Values

Your team has values even if you haven’t expressed them. Really, you should have let the new developer know what your team’s values were before they joined so they knew what they were getting into. By being explicit to new teammates about what these values, you give them confidence in making decisions that exercise those values, especially as you give them more autonomy in the months ahead. Furthermore, you give them the ability to help you prune practices from your team that may not be aligned with those values.

Thanks to Frank Carnevale for inspiration for this post.