How to develop a team-based onboarding experience

Background/Motivation

In a large enterprise environment, you may have a high-level onboarding experience for all developers at your company. However, such an experience will not necessarily prepare new hires or transfers for actually working in their individual teams.

Within a large company, you may have teams using lots of different technology stacks or practices. There may be no single developer onboarding experience at the company level.

Individual teams have the greatest impact on whether new developers have the material and support they need to do their work. This is a guide for writing your team's specific onboarding material.

Tips and Best Practices for Onboarding New Developers to Your Team

• Document everything! The goal is to reduce verbal-based "tribal knowledge" by writing things down. By documenting everything, you enable developers to work asynchronously and learn things when team members are not available to help. This is especially important for organizations that allow people to work flexible hours or different time zones. 🌎🌏
• At the same time, recognize that people have different learning styles! It's not always going to be appropriate to send a bunch of documentation links to the new member of your team. Try to strike a balance between sharing documentation and talking to your new teammate so that they can learn to help themselves while still connecting with you, their new team.
• Make minimal assumptions about what people "should" know! New hires or transfers may join your team with zero experience working with the specific tools and technologies that your team uses. This goes for programming languages, infrastructure, design patterns, Computer Science concepts, etc. Don't worry - this does not mean that you need to write something like a Beginner's Guide to JavaScript. It means that you should be mindful that your new teammate may not be super familiar with a given topic.
• Use links to direct people where to learn more about a topic. A "references" section at the top or bottom of your documentation is a helpful place to include links for learning more about topics.
• Writing about code is hard! Consider using diagrams! ⏹🔄⏺
• Spend some time considering which processes and technologies that your code depends on. What do developers need to understand about these dependencies? Do you know who to contact or where to look if you need to learn more about something your team doesn't directly own or maintain?

Team Onboarding Documentation Checklist 📝

• Your team has its own documentation page in the space where R&D documentation is kept (e.g. Confluence)
• Team contact information. Things to consider:
  • How to contact the team for escalations or production incidents 🚨
  • Where to ask for help / non-urgent questions 🤔
  • How to ask for feature requests 🙏🏻
• Team members and their roles
• Team Charter or Mission Statement (usually a 1-2 sentence describing what your team does)
• Team's current Objectives and Key Results
• List of owned features and links to their documentation
• Slack or Microsoft Teams Channels that team members should know about
  • Required channels ⭐️
  • Optional channels
• Email distribution lists to join
• Things to get access to (e.g. authorization roles)
• Team processes (if different from company processes)
  • What is expected in your team's code review and QA testing process?
  • Developer on-call duties 📟
    • Rotation Schedule
    • Requirements (get access to X, subscribe to status updates with Y, etc)
    • Responsibilities (respond to alerts, write on-call shift notes, etc)
    • What to do if you can't respond to a page
    • Links to any feature-level on-call runbooks

Related Posts I've written

1. Production-Ready Feature Documentation Checklist
2. Tanking For Your Team: A Tech Lead's Guide to the On-Call Developer Role

References

1. Production-Ready Microservices: Building Standardized Systems Across an Engineering Organization by Susan Fowler
2. The DevOps Handbook: How to Create World-Class Agility, Reliability, & Security in Technology Organizations by Gene Kim, Jez Humble, John Willis, Patrick Debois
3. OKR: Learn Google's Goal System with Examples and Templates