Developer Onboarding Checklist: Put DevEx First

Anyone who has been reading this blog or who has worked at Cortex can tell you that we are quite passionate about Developer Experience (DevEx). But just what is DevEx, and how does it relate to onboarding new developers? It's a fair question, since the word can mean different things in different contexts. We are even on the record as saying that definitions are necessarily vague to allow for DevEx being inherently subjective to a given environment. We would love to use the word "vibes", but unfortunately, this is an engineering blog. Let's get into it.

The Role of Onboarding in DevEx

DevEx is a measure of how well a development culture and environment incentivize and enable good work. It encompasses everything from technology, architectures and work processes to communication, incentives and emotional support. Because it is a holistic measure of culture and expectations, your onboarding program is central to good DevEx as a way to set the tone and get new employees up to speed. High performance organizations are exceptional by definition, and onboarding imparts these standards and expectations that drive these cultures right from the start.

Employee onboarding is not just an opportunity to inform and educate about your company's DevEx. If done right, it should be seen as the first step in driving standards and optimizing your developer experience. Ambitious companies should see onboarding as a proactive driver of DevEx, rather than a passive means of passing on information. It allows you to streamline the integration of new developers, ensuring they quickly become valuable, contributing members of your team.

So if onboarding helps optimize DevEx, how can you optimize your onboarding plan?

Benefits of a Developer Onboarding Checklist

While DevEx is subjective in aggregate, a great deal of it can be defined by best practice. Checklists are the best way to systematize expertise and good practice when delivering repeated tasks. Using a developer onboarding checklist ensures that crucial parts of onboarding are delivered as standard and to spec.

This can in turn lead to the following benefits:

Streamline the Onboarding Process

A well-crafted checklist ensures that all necessary onboarding steps are followed systematically, reducing the risk of oversight or inconsistency. It provides a clear roadmap for the new employee, the hiring manager and the onboarding team, ensuring that key tasks are completed in a structured and methodical way. Benefits include:

• Reduced time-to-productivity for new hires: By providing all necessary tools, access, and information upfront, an onboarding checklist enables even junior developers to start contributing quickly. Laying out documentation, tools and ownership gets joiners up to speed quickly, and providing clear and specific milestones helps them understand their new role and start adding value from the off.
• Enhance job satisfaction and retention rates: An organized and supportive onboarding fosters a sense of belonging and confidence among new hires. This positive initial experience helps new team members to build confidence and foster positive relationships from the start, which leads to higher job satisfaction and the associated benefits in retention rates.
• Facilitate Consistent Knowledge Transfer: A standardized onboarding checklist ensures that all new hires receive the same foundational knowledge and training, promoting consistency across the team. This guarantees the uniform understanding and knowledge retention needed for a high standard of work, while preserving institutional knowledge with its associated competitive advantage.

Common Challenges in Developer Onboarding

Building an onboarding process is not easy. Maybe some of the software engineers defining technical standards are unwilling to get involved, you’re lacking capacity or you are unsure how to define the DevEx that you wish to impart. It can feel overwhelming.

Some challenges include:

Navigating Diverse Tech Stacks and Tools

On their first day, software developers often encounter a variety of tech stacks and tools, some specific to the organization. Understanding and learning how to use these new tools can be overwhelming, delaying productivity and even causing new hires to become frustrated. A checklist that includes tutorials and access to comprehensive documentation can help move through this phase quickly.

Bridging Knowledge Gaps and Learning Curves

As well as new tools, there are often new development processes and knowledge gaps in how to build software. These inconsistent skill levels can lead to a longer ramp-up time, delaying the time to value for new hires. Your checklist might include mentorship and buddy programs to help bridge this gap, or even personalized learning paths with relevant training resources.

Building Team Cohesion and Culture Fit

Helping new hires to quickly feel that they are part of the team and aligning them on company culture is an essential part of improving DevEx. Failure to get it right can lead to isolation, disengagement and even churn. Your checklist should include cultural sessions and team-building or social activities, including for remote workers. Culture is too important to be left to chance.

A Sample Developer Onboarding Checklist

Let's consider what you might include on your checklist to ensure that your new developers all get the best treatment.

First you'll want to cover off everything that needs to be done internally ahead of their arrival.

Pre-Onboarding Preparations

• Prepare a workstation with all necessary hardware and software (if in-person)
• Arrange for delivery of necessary hardware setup (if remote)
• Ensure all access credentials and accounts are set up
• Schedule a casual welcome meeting with their new team lead and/or buddy that touches on company culture
• Prepare welcome materials, including an employee handbook, welcome letter and introductory documents

Then consider what they will need to feel welcome and relaxed on their first day.

First Day Essentials

• Schedule a welcome meeting with HR and the immediate team to form a positive first impression
• Share a new hire announcement with the wider team
• Introduce developer to essential tools, apps and platforms  
• Ensure access to relevant technical documentation and knowledge base
• Organize office tour and setup of the development environment (virtual tour if remote)

It helps to build in clear objectives from the first week to give the new engineer something to get their teeth into, and to emphasize a culture of getting stuff done.

First Week Objectives

• Complete technical setup, including IDEs, version control, and project management tools
• Provide detailed briefing on your company's products and clients
• Conduct meetings with key stakeholders and extended team members
• Attend initial training sessions covering company policies, security protocols, and development practices
• Complete small, non-critical tasks that can ease the new employee into the role and help them to build confidence

During the first month you want the developer to feel like they belong and start adding real value to the engineering team.

First Month Goals

• Establish feedback loops formally and informally, including regular one-on-one meetings with managers and buddy: ensure multiple touchpoints to prevent single points of failure
• Assign small, manageable projects or tasks to help new hires get hands-on experience
• Conduct regular progress reviews, including a formal evaluation at the end of the month to assess progress and address any concerns
• Start training to improve skills and/or get coding style more in line with company culture

When we talk about access to tools, it helps to list these out in detail to ensure nothing slips through the gaps.

Access to Essential Tools and Platforms

• Set up accounts for version control (e.g. GitHub, GitLab, Datadog)
• Provide access to project management tools (e.g. Jira, Trello, Asana)
• Ensure setup of communication tools (e.g. Slack, Zoom, Microsoft Teams)

Putting in the work required for a functional development environment early on is a way to put new hires at ease and allow them to get to grips with the role.

Development Environment Setup

• Install and configure necessary IDEs and development tools (e.g. Visual Studio Code, IntelliJ IDEA, Eclipse)
• Assist in cloning necessary repositories to the local machine
• Support setup of local databases, including installation and configuration (e.g. MySQL, PostgreSQL, MongoDB)
• Explain the branching model employed (e.g. Gitflow, trunk-based development) and describe the branches corresponding to various environments (e.g. develop, production)
• Guide through the setup of local development environments, including databases and containerization tools if used (e.g. Docker, Kubernetes)

The orientation on your codebase should be thorough, and conducted as soon as the new hire feels comfortable and settled.

Codebase Orientation

• Conduct review of key projects and services for their team, touching on wider company goals
• Offer a detailed walkthrough of the project's repository structure, highlighting key directories
• Introduce coding standards, including code review processes, standards and tools
• Provide an overview of the CI/CD pipelines, including what happens at each stage and the tools and technologies used
• If applicable, give an overview of microservices architecture that includes external dependencies or libraries

Security and compliance warrant a specialized work stream with its own section on your onboarding checklist. While there is overlap between this section of onboarding and other technical streams, software developers will benefit from covering this more than once.

Security and Compliance Training

• Provide overview of security protocols, laying out the organizations security and data handling policies as well as explaining why they are important
• Touch on secure coding practices, emphasizing coding standards and code scanning tools that are covered elsewhere in technical onboarding
• Offer further briefing on security scanning tools installed while setting up the developer environment (e.g. Snyk, OWASP ZAP)
• Brief on incident reporting and response protocol for reporting security incidents and vulnerabilities, including an overview of the incident response plan
• Introduce tools for managing passwords and credentials securely (e.g. Vault, AWS Secrets Manager)

It is important to take the time to help a new hire feel welcome and included in the team, so your checklist needs to formally include and prioritize this aspect of onboarding.

Company and Team Introductions

• Organize a welcome meeting with the team and key stakeholders, including developers, product managers, designers and QA analysts
• Share the company history, mission, values, and culture
• Explain the organization structure, highlighting key departments and leadership
• Assign a mentor and/or buddy for the first few months (if you haven't done this in advance of starting)

As well as technical policies and approaches, it is important to provide an overview of broader company procedures and policies.

Overview of Company Policies and Procedures

• Discuss HR policies, typical work hours, norms around booking and attending meetings, and communication protocols, both within the development team and more broadly
• Explain remote work policies and office space usage, if applicable
• Introduce any diversity policies or training
• Showcase employee recognition programs and celebration of milestones, if applicable

Company culture is too important to pick up by osmosis, and should feature in your checklist.

Integration into Company Culture

• Invite to company-wide and team-specific events, explaining the role these play and why they are important
• Conduct a session on your company's values and mission orientation, providing tangible examples of how these effect day-to-day decision making
• Clarify any norms around political speech or other non-core communication
• Introduce to interest groups or clubs within the company, if applicable

Clarifying expectations around growth and professional development helps your new developers to start setting and pursuing goals from day one.

Professional Growth and Expectations

• Set clear expectations for the first 30, 60, and 90 days
• Lay out roles and responsibilities at all levels, indicating what is needed to secure a promotion
• Discuss professional development opportunities and career paths within the company

Feedback is essential to DevEx, as management will only ever get a limited insight into developers' experience on the coalface. Your checklist should actively schedule sessions and help you to collect feedback for the continuous improvement of the developer and the organization.

Feedback and Continuous Improvement

Regular Check-ins

• Schedule weekly one-on-ones with the manager or mentor for the first month
• Establish clear feedback mechanisms for discussing company matters, starting with the onboarding process

Feedback Sessions

• Conduct a formal onboarding feedback session after the first month
• Provide a platform for continuous feedback on the onboarding process, with the option of sharing feedback anonymously

Why Tools and Environment Are Important for Developer Onboarding

Considering DevEx relates to your ability to do good work sustainably, it stands to reason that tooling and environment are crucial to getting it right. Onboarding ties all of this together, reducing the learning curve required to operate in this development environment and use relevant tools efficiently. Margaret-Anne Storey concluded in a recent DevEx study that working environment determines flow states and ability to focus, which are crucial to satisfaction and productivity. Your environment should enable communication while minimizing interruptions - this requires careful and deliberate planning. A sense of shared mission and belonging allows team members to do their best work, so it's important to ensure that onboarding proactively fosters this.

Cortex's Justin Reock, in an excellent piece on DevEx, quotes the researchers behind SPACE when saying that DevEx comes not from one metric but from "a constellation of metrics in tension". He explains that DevEx derives from the full stack of build, deployment and management tools. These tools accelerate learning and productivity: best practice tool selection and environmental setup need to be built into onboarding to prioritize DevEx for new hires.

Using tools in onboarding

An Internal Developer Portal can make a big difference to onboarding if used correctly.

Start with consistency. Consistent development standards across teams improves DevEx, and here the Cortex Scaffolder can help from day one. By enabling project templates and boilerplate code, your new hires can get from idea to production-ready code quickly. Templated services and resources provide them with efficient bootstrapping for new entities, including input validation for owners, groups, and dependencies.

Onboarding is a jump-off point to allow new recruits to start adding value, and developers will want to stand on their own feet as soon as possible. They will be quickly assessing needs and requirements for projects, documentation and dependencies for software entities, and visibility across the development environment. Cortex Workflows can help speed time to impact by automating account setup processes that often require manually filing tickets and waiting for approval. Our Catalog gives new and existing developers access to all dependencies, documentation, change history and ownership information in one place. New hires can complete onboarding comfortable in their ability to find and assess details for all software entities.

DevEx is about more than just culture and environment: it requires clear expectations on what developers should work on and how. Scorecards allows setting and tracking standards for production readiness, development quality, security compliance and more, using dynamic, real-time data. This gives clear indications of what is expected from new hires, and places their work in the broader context of the organization's goals. Scorecards  allow new developers to make informed decision-making using insights into software health, progress, while identifying bottlenecks and risks.

Incorporating Feedback and Continuous Improvement in Onboarding

Like all that we love in technology and capitalism, onboarding is a living process that cannot remain static. It is a journey not a destination, and getting it right means having incentives and constraints to improve the process, as well as feedback mechanisms to surface opportunities and concerns.

Efforts to gather feedback and data, such as one-to-one catch-ups or surveys on completion of onboarding, should be included on your onboarding checklist. Surveys and questionnaires are good ways to review the process, and should be administered at several intervals. Just make sure that it doesn't become a chore: track completion rates and consider reducing the length or number of open-ended questions to get this number up. Ongoing mentorship and coaching should also provide a capacity for both parties to informally share feedback on the process, even months after it has concluded.

This feedback and data should be compiled and reviewed, paying particular attention to recurring pain points and bottlenecks in the process. It helps to review historical feedback in the context of a given developer's contributions at the company, to ensure that your changes are optimized for identifying and enabling high performers.

Any insights that you glean should lead to incremental changes over sweeping reforms, unless you find something that has gone very wrong. This might include enhanced documentation captured in the Catalog, or streamlined communication enabled by scorecards. It might also cause you to make onboarding paths more personalized to the individual, or increase the interactivity of training sessions. Having the data from your feedback gives you more credibility when implementing these changes in your company.

Measuring the Success of Your Developer Onboarding Process

Metrics relating to engineering and code quality double up as useful indicators of successful onboarding. If you use SPACE or DORA metrics more broadly then find a way to tailor them to onboarding, and it's worth considering DevEx metrics specifically.

Metrics that you can use to assess your onboarding include the below:

• Code Review Feedback: Measure the quality and frequency of feedback received during initial code reviews for new starters. A low level of issues raised from early on indicates effective training on coding standards.
• Commit Frequency: Track the rate at which new developers are committing code. A quick ramp up in commit frequency suggests growing confidence and integration into the development workflow from the beginning.
• Bug Rates: Monitor the number of bugs reported in the code written by new hires. Starting from a low base reflects a firm understanding of code quality from onboarding.‍
• Lead Time for Changes: Measure the time it takes for new hires to go from code committed to code successfully running in production. Shorter lead times suggest quicker adaptation to the development culture and workflow.‍
• Pair Programming Sessions: Measure the number and quality of pair programming sessions attended by new hires. Higher participation suggests better knowledge sharing and collaboration.

Case study: Greenhouse

As a SaaS company in the recruitment space, Greenhouse knows the value of onboarding. After a bumper year for new hires in 2019, the company replaced an ad-hoc onboarding experience with a structured approach. This emphasized the need to get hires contributing as quickly as possible, adding a formal buddy program and taking a product mindset based on iterative improvement. As well as improving outcomes for new hires, Greenhouse was able to codify findings within its onboarding product and turn internal innovation into a product improvement that drives revenue.

Case study: Asana

Asana focuses on new developers as teammates and individuals first, and technical contributors second. They combine an onboarding process packed with meetings, training and walkthroughs with a rule that new hires must ship something on their first day. This provides engineers with a soft landing and psychological safety, without neglecting the importance of technical contribution.

Asana's emphasis on team over speed differs from Greenhouse, and shows the subjectivity of onboarding processes that should be reflected in your associated checklist.

Case study: Zapier

Onboarding for a fully-remote company comes with its own challenges, something that we are familiar with at Cortex. Zapier emphasizes communication with HR, mentors, team members and other stakeholders, explaining meeting etiquette and how to use Slack and Zoom from the start of onboarding. The company invests in relationships, flying new hires to California for a week after the four-week onboarding process is completed. It combines this with a decentralized approach to learning, sharing self-service materials prepared to help those who prefer to learn alone on their own time.

Onboarding remote developers: Strategies and considerations

All checklists should take into account the subjective needs of your company, and this is especially true when onboarding remote workers. Getting hardware setup as well as account creation and login details sorted in advance helps joiners to focus more on their role from day one, and checklists should set work to start dates while allowing for delays or bottlenecks to get this right.

When building or revising a checklist for remote employees, consider how you may need to adjust your delivery for each item. Every training session, buddy intro and code review will be perceived differently over video call, so observe how this works in practice and gather data as you go. Team building is more difficult when done remotely but that makes it all the more important: consider annual or quarterly meet-ups to build camaraderie.

It is particularly important to set clear norms and expectations around remote communication. Deep work is central to good DevEx, and it is impossible with frequent interruptions. Good DevEx often translates as getting out of your developers' way, and once you have solved for this you should build it into your onboarding.

For more information on how Cortex might help with developer onboarding, take a tour of the product, or book a custom consultation today.