Blog
/
/
Ultimate developer onboarding checklist for 2024
Internal developer portal

Ultimate developer onboarding checklist for 2024

Sooraj Shah
Jul 23, 2024
Sign up
Download PDF
Internal developer portal

What is developer onboarding?

Developer onboarding involves bringing new software developers into an established team and helping them understand the team's workflows, procedures, and tools. It also helps them get acquainted with the software engineering standards in place, the company’s culture, on-call rota and time-off policies. This process provides new developers with the essential knowledge and resources they need to begin delivering software with an understanding of the SDLC. 

A tangible measure of success of developer onboarding can be time to productivity, such as time to first commit and self-reported metrics that originate from self-reporting (e.g. a survey).

Developers that take months to make a first commit as a result of a poorly defined onboarding process cost the organization too much, and are probably not having a good experience. Developers that are provided with the ability to understand what’s going on and begin being productive will have a better experience and will deliver value faster, which means the business recoups the investment in hiring and onboarding much faster.

Why is developer onboarding important?

Developer onboarding is important to ensure everyone is aligned from day one. HBR found that new employees that have a structured onboarding process are more likely to stay at the company for a longer period (50% greater new hire retention), and are more likely to be able to contribute faster to their organization’s work (62% greater new hire productivity). This is likely to have stemmed from positive sentiment about the way the organization and the team work, and from a sense of inclusion into the team’s workflow as well as a sense of ownership over their work. 

Improving developer experience - how developers feel, think and value what they do - is a big focus for engineering teams. A GitHub, Microsoft  and DX study on the topic, found that developers who found their tools and work processes intuitive and easy to use felt that they were 50% more innovative compared to those with hard to understand processes. The study found that unintuitive tools and processes can be both a time sink and a source of frustration. The study demonstrated the link between developer experience and developer productivity and satisfaction.

The report highlighted that there is a difference between simply writing code and writing code in an environment that is optimized for writing code; environments that are optimized for writing code are efficient, effective and conducive to wellbeing, and they rely on the right mix of tools, practices, processes and social structures. That environment should be ready at the onboarding stage. 

The ultimate developer onboarding checklist for 2024

So now you know everything you need to know about developer onboarding and you just want to get started. Here’s the checklist you need:

1. Pre-onboarding: what needs to be prepared beforehand

Before your new developer starts, you should ensure they’ve completed all the relevant paperwork and requested (and received) the appropriate equipment if they’re working remotely.

They should be welcomed officially - an email (and/or letter) explaining their start date, time, office address, where they can meet you and any other information that they need should be sent to them a week prior. This can also include further details about the company and team’s culture.

The email should also provide an itinerary for the first day, to manage their expectations. This could include the people they’ll be meeting and any onboarding tasks that need to be completed.

2. The first day

Meet the team

  • The hiring manager should meet with them first, show them around the office (if not working , and have an informal chat to discuss the day and the week, as well as checking in later in the day.
  • Depending on the organization, HR can provide more details on the organization’s social events, culture, and people they need to know.
  • Deploy a ‘buddy system’, where you have one seasoned employee paired with a new hire. This is their go-to person for any questions or assistance, and they can provide more clarity on workflows and processes.
  • Ensure you create and foster relationships between your new hires and leadership along with teammates in other key departments - for example, in security or product.
  • Create a Slack (or whatever your choice of collaboration software is) for new starters where they can join.
  • Don’t overwhelm your new starter with a ton of information in one day, any other important tasks and meetings can take place throughout their first week. 

Workplace setup

  • Provide the developer with an up-to-date onboarding playbook and show them the documentation they’ll be using.
  • The base image or common set of software tools may be pre-installed on the device or may be outlined in a doc for the developer to easily install. These include browsers, email software, productivity tools, collaboration software and security software.
  • The base developer image, or developer-specific tools required, which include:
    • Language specific software development kits, or SDKs, such as the ones for Python, Go and Java. After all, you need to compile or interpret your code, the ability to package it up.
    • Integrated development environment (IDE), so that you can write your code along with any applicable plugins and the ability for developers to install some of their own favorite and hopefully approved plugins.
    • Command line - therefore having a terminal and a default shell is extremely important, along with the ability for developers to install and configure their favorite shell.
    • Git for version control management, along with various command line tool interfaces.
    • CLIs depending on what your team does (eg. cube CTL, or the CLI for your cloud provider used at your organization, for example, Google Cloud).
    • Virtual environment tools like Docker and virtual box.
    • Other supporting tools required by your team, such as Postman and Homebrew.

Provide curated information that helps developers onboard

To succeed in quickly understanding what is expected of them as well as the environment, the tools, the SDLC, underlying technologies and more, developers need to have all that information collected for them and curated in a way that will make onboarding as simple and quick as possible.

Onboarding developers is about providing access to documentation, code samples, quality and security standards, understanding approvals and reviews, APIs, ways of collaboration and more. IDPs (internal developer platforms) can provide that in one place. When developers access the internal developer portal, they can see all microservices, environments and dependencies, abstracted by their role, see the relevant documentation, APIs, tooling and even easily see who is the owner of a service. This alone can save much time for developers. 

Golden paths

Golden paths provide a balance between giving developers complete freedom and requiring DevOps to manage everything meticulously - just to ensure developers don’t veer of course. The golden path means that standards set by platform engineers are easily adhered to as they are embedded into tasks that developers can accomplish independently. This involves using automation or self-service options. By providing developers with golden paths, it’s easier for them to get to their first commit. 

Role clarity

  • Go over responsibilities and set expectations. Answer any questions the developers have about the role.
  • Explain the daily and weekly routine.
  • Provide an example of tasks or share a current project with the developer, to give them an idea of what’s to come.

3. Within the first month

Setting up early wins

  • Time to first commit is a metric used to define when the new starter begins working to the time when they’ve landed their first commit in the version control system. The shorter the gap, the higher the chance for the developer to remain in the job (and be satisfied there). Here, the onus is on the organization to have an environment that enables developers to get to work quickly, providing them with the right support, tools, and an organized codebase, easy-to-find documentation, efficient testing processes, and mature CI processes.
  • It’s important to check whether the task you’re measuring is appropriate to gauge how quickly you’re onboarding developers. For example, measuring the time it takes for a significant PR request can be difficult because defining a ‘significant’ PR request is subjective and it does not necessarily reflect on the environment as a whole.

Regular check-ins and feedback

  • Building rapport with your new developer is crucial, so regular check-ins are a good way to ensure the dialogue is always kept open.
  • It’s also important to take their feedback about the processes, workflows and culture seriously. Perhaps they’ve come from an environment where PR reviews are faster or MTTR is lower - they should be able to suggest new ways of doing things - ensuring that they feel empowered and feel part of the team.
  • You should also encourage other members of the team to check-in on how the new starter is faring.
  • One way of gaining feedback is through developer onboarding surveys. (Note: you should also survey developers at regular intervals about their day-to-day work to help improve the overall developer experience).
  • The mentor or buddy should sit down with the developer at the end of each day in the first week or so, and review the code, answer questions, and provide advice.

How an internal developer portal can help with developer onboarding challenges

The key challenge organizations face is the number of developers that they need to onboard and provide them with the tools and permissions to get started so that they can become a productive part of the team.

This becomes difficult as organizations scale as:

  • They don’t have an efficient way to provide developers with the documentation and information they need.
  • There’s a steep learning curve for all of the different tools.
  • Developers are likely to need answers on a number of issues stemming from approvals and access requests, ownership of services, service dependencies and navigating and context-switching between different tools. However, as organizations scale they can’t rely on mentors or buddys to assist every developer, and the time it takes to answer questions and provide them with the information required is effectively a cost to the business. 

An internal developer portal can help by providing new starters with golden paths; platform engineers can configure self-service forms with predefined standards, enabling developers to select from a variety of options and independently execute an action such as creating a new Kubernetes cluster or spinning up a new dev environment. They can then monitor the standards of their existing resources such as changes to version or security settings - automatically through scorecards which grade the level of standards compliance. Finally, if a resource is found to be noncompliant, developers are able to correct these issues and return to the golden path.

The portal’s software catalog provides all information they need about services, resources and APIs such as ownership, dependencies, on-call information, documentation, and more.

Together, a software catalog, self-service actions,and scorecards, can provide developers with the golden path they need so that they don’t lose their way, reducing the cognitive load for developers. For new hires, these capabilities are even more beneficial as they can better understand what to set up (base image, developer image), how to set up, how the processes work (documentation), what the resources are all about (software catalog), the standards of the organization (scorecards), and the means to get things done independently (self-service actions).  

Below you can see the different onboarding challenges and how the portal can help you to overcome them:

| | Onboarding challenge | How the portal helps | |----|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | Context-switching & learning curve for different tools | Provides a unified interface which integrates all developer tools and abstracts away any complexity (for eg. Kubernetes), providing them with the information and access they need, easily. | | 2 | Getting information and resources they need to get set up | The software catalog offers a clear view of the technology stack, ownership details, and dependencies, reducing dependence on tribal knowledge sharing. | | 3 | Waiting for approvals for access | Self-service actions cut wait times for tool access, like obtaining cloud resource permissions or setting up environments. They ensure golden paths are followed and guardrails are baked-in. | | 4 | The time it takes for the developer to begin productive work | The speed of initial commits is enhanced with golden paths provided, and customized dashboards that show resources, metrics, and onboarding documents. | | 5 | Getting an understanding of engineering standards in the organization | By defining and tracking standards for production readiness, security, FinOps, and more through scorecards, your new hire can get a better understanding of what standards are expected. |

Further reading:

Want to learn more about the internal developer portal? Read our guide here.

Or read our guide to the top 10 things internal developer portals must have.

{{cta_1}}

Check out Port's pre-populated demo and see what it's all about.

Check live demo

No email required

{{cta_2}}

Contact sales for a technical product walkthrough

Let’s start
{{cta_3}}

Open a free Port account. No credit card required

Let’s start
{{cta_4}}

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start
{{cta_5}}

Check out Port's pre-populated demo and see what it's all about.

(no email required)

Let’s start
{{cta_6}}

Contact sales for a technical product walkthrough

Let’s start
{{cta_7}}

Open a free Port account. No credit card required

Let’s start
{{cta_8}}

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start
{{cta-demo}}
{{reading-box-backstage-vs-port}}

Example JSON block

{
  "foo": "bar"
}

Order Domain

{
  "properties": {},
  "relations": {},
  "title": "Orders",
  "identifier": "Orders"
}

Cart System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Cart",
  "title": "Cart"
}

Products System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Products",
  "title": "Products"
}

Cart Resource

{
  "properties": {
    "type": "postgress"
  },
  "relations": {},
  "icon": "GPU",
  "title": "Cart SQL database",
  "identifier": "cart-sql-sb"
}

Cart API

{
 "identifier": "CartAPI",
 "title": "Cart API",
 "blueprint": "API",
 "properties": {
   "type": "Open API"
 },
 "relations": {
   "provider": "CartService"
 },
 "icon": "Link"
}

Core Kafka Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Kafka Library",
  "identifier": "CoreKafkaLibrary"
}

Core Payment Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Payment Library",
  "identifier": "CorePaymentLibrary"
}

Cart Service JSON

{
 "identifier": "CartService",
 "title": "Cart Service",
 "blueprint": "Component",
 "properties": {
   "type": "service"
 },
 "relations": {
   "system": "Cart",
   "resources": [
     "cart-sql-sb"
   ],
   "consumesApi": [],
   "components": [
     "CorePaymentLibrary",
     "CoreKafkaLibrary"
   ]
 },
 "icon": "Cloud"
}

Products Service JSON

{
  "identifier": "ProductsService",
  "title": "Products Service",
  "blueprint": "Component",
  "properties": {
    "type": "service"
  },
  "relations": {
    "system": "Products",
    "consumesApi": [
      "CartAPI"
    ],
    "components": []
  }
}

Component Blueprint

{
 "identifier": "Component",
 "title": "Component",
 "icon": "Cloud",
 "schema": {
   "properties": {
     "type": {
       "enum": [
         "service",
         "library"
       ],
       "icon": "Docs",
       "type": "string",
       "enumColors": {
         "service": "blue",
         "library": "green"
       }
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "system": {
     "target": "System",
     "required": false,
     "many": false
   },
   "resources": {
     "target": "Resource",
     "required": false,
     "many": true
   },
   "consumesApi": {
     "target": "API",
     "required": false,
     "many": true
   },
   "components": {
     "target": "Component",
     "required": false,
     "many": true
   },
   "providesApi": {
     "target": "API",
     "required": false,
     "many": false
   }
 }
}

Resource Blueprint

{
 “identifier”: “Resource”,
 “title”: “Resource”,
 “icon”: “DevopsTool”,
 “schema”: {
   “properties”: {
     “type”: {
       “enum”: [
         “postgress”,
         “kafka-topic”,
         “rabbit-queue”,
         “s3-bucket”
       ],
       “icon”: “Docs”,
       “type”: “string”
     }
   },
   “required”: []
 },
 “mirrorProperties”: {},
 “formulaProperties”: {},
 “calculationProperties”: {},
 “relations”: {}
}

API Blueprint

{
 "identifier": "API",
 "title": "API",
 "icon": "Link",
 "schema": {
   "properties": {
     "type": {
       "type": "string",
       "enum": [
         "Open API",
         "grpc"
       ]
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "provider": {
     "target": "Component",
     "required": true,
     "many": false
   }
 }
}

Domain Blueprint

{
 "identifier": "Domain",
 "title": "Domain",
 "icon": "Server",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {}
}

System Blueprint

{
 "identifier": "System",
 "title": "System",
 "icon": "DevopsTool",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "domain": {
     "target": "Domain",
     "required": true,
     "many": false
   }
 }
}
{{tabel-1}}

Microservices SDLC

  • Scaffold a new microservice

  • Deploy (canary or blue-green)

  • Feature flagging

  • Revert

  • Lock deployments

  • Add Secret

  • Force merge pull request (skip tests on crises)

  • Add environment variable to service

  • Add IaC to the service

  • Upgrade package version

Development environments

  • Spin up a developer environment for 5 days

  • ETL mock data to environment

  • Invite developer to the environment

  • Extend TTL by 3 days

Cloud resources

  • Provision a cloud resource

  • Modify a cloud resource

  • Get permissions to access cloud resource

SRE actions

  • Update pod count

  • Update auto-scaling group

  • Execute incident response runbook automation

Data Engineering

  • Add / Remove / Update Column to table

  • Run Airflow DAG

  • Duplicate table

Backoffice

  • Change customer configuration

  • Update customer software version

  • Upgrade - Downgrade plan tier

  • Create - Delete customer

Machine learning actions

  • Train model

  • Pre-process dataset

  • Deploy

  • A/B testing traffic route

  • Revert

  • Spin up remote Jupyter notebook

{{tabel-2}}

Engineering tools

  • Observability

  • Tasks management

  • CI/CD

  • On-Call management

  • Troubleshooting tools

  • DevSecOps

  • Runbooks

Infrastructure

  • Cloud Resources

  • K8S

  • Containers & Serverless

  • IaC

  • Databases

  • Environments

  • Regions

Software and more

  • Microservices

  • Docker Images

  • Docs

  • APIs

  • 3rd parties

  • Runbooks

  • Cron jobs

Let us walk you through the platform and catalog the assets of your choice.

I’m ready, let’s start