Improve developer onboarding with an internal developer portal

‍This post originally appeared in The New Stack on November 8, 2024. 

Introduction

Developer onboarding essentially boils down to educating a new teammate on your software development lifecycle (SDLC) so that they can deliver software. According to the Society for Human Resources Management, about 70% of new employees in the US stay at a company for more than three years if they have a positive, well-structured onboarding experience. This also boosts their productivity and retention rates to 58% and 60%, respectively. 

But if you’ve ever onboarded a new teammate — or have been onboarded yourself — you know how time-intensive a task this can be. Sometimes, you spend more time answering questions and providing feedback to a new developer than performing tasks associated with your actual role. 

Onboarding a new developer consumes so much time and resources that it often appears as its own task in a sprint, which takes away time the team could be spending working on new features. On the flip side, the new developer already has to learn so much about their company culture, policies and colleagues — the last thing they need is an inefficient onboarding experience! 

In this post, we’ll discuss how an internal developer portal will streamline your onboarding experience and address numerous onboarding challenges. 

Challenges with onboarding new developers

Though we’ve briefly discussed the high-level challenges that come with onboarding new developers, there are specific pain points that an internal developer portal can solve. These include:

• Lack of defined onboarding processes: The biggest factor in retaining employees in the long term is the quality of their onboarding process, but many are not likely to have well-defined processes.
• Provisioning tools, access control and visibility: A new developer must be given access to every part of their new software development lifecycle (SDLC). They also may not be able to see other related services in certain tools unless they are given full edit permissions, which can introduce unnecessary risk. Overall, it can sometimes take up to 10 days to grant a new developer access to all of the services they need.
• Understanding the code & related software instructure: Every application is unique and complex! Understanding the relationships between different services, runtime resources, and engineering teams can take months to grasp.
• Providing tasks and templated actions: The end goal of onboarding is to add an effective new member to your team — what better way is there than to provide them exactly what they need to get started? Templated tasks and actions make developers autonomous much more quickly, reducing their time to productivity.

A developer needs to remember a lot, such as the order of onboarding tasks, how to deliver role-specific permissions, how services interact with one another — on top of delivering new features or making commits as usual. Let’s dive into each of these friction points and examine how an internal developer portal resolves them.

Onboarding challenge 1: Lack of defined onboarding processes

Research shows that a structured onboarding process can increase employee productivity by as much as 50%. Though onboarding new developers is an essential part of building a successful workplace, arriving at the outcome of onboarding typically appears more valuable than documenting the process. 

DevOps or platform engineers often bear the brunt of early onboarding because they must provide access and figure out:

• Which tools each developer needs access to
• How to design their permissions
• What level of visibility each developer needs into other team setups based on their role

The work of figuring all of this out consumes valuable time for teams every time a developer has to be onboarded. Without a clear process in place, developers may feel overwhelmed by the complexity of their role, unable to easily identify service owners or best practices and overall disengaged from their new team. Not only does this negatively impact your new developers, but it also puts additional strain on your existing team who are responsible for acclimating the new developer to their engineering environment. 

An internal developer portal provides you the tools you need to create specific onboarding structures for different, common developer personas. This kind of view offers many benefits over the traditional onboarding process (or lack thereof), including repeatability, specificity, and standardization of the onboarding experience more generally. 

A structured onboarding experience within a portal drastically reduces the amount of preparation needed to onboard new employees and standardize the process, ensuring that the onboarding experience is consistent and straightforward for all new developers. In turn, this boosts new developer satisfaction and engagement, sometimes by nearly 70%.

Take a look at the below example which shows a Plan My Day experience for developers that includes everything they need to plan work for their day:

To learn more about building onboarding and other experiences in Port, watch this short video on planning experiences in an open internal developer portal, which uses the example of a developer’s daily tasks.

Onboarding challenge 2: Provisioning tools, access control, and visibility

Without proper access to tools and software, a developer can’t make their first commit or do anything of value. On the other hand, if a developer has too much access, that can introduce privacy and security concerns.

In an onboarding context, it can be difficult to keep track of which services each developer needs access to and how much access or the type of access they need. This can also change over time as developers leave the company, move teams or projects, or need special permissions to accomplish one-off tasks, which adds to the complexity of permissioning for DevOps and platform teams.

If you’re onboarding external developers, including vendors and contractor teams, additional concerns arise when they need access to sensitive production environments or release pipelines to enable new software or build features. 

An internal developer portal resolves these concerns with RBAC, which can be designed to grant and revoke access to different services based on time limits as well as role within the organization. Importing SSO also helps you batch permissions by importing an external team’s infrastructure into your portal:

An internal developer portal also further enables you to control what each developer sees, has permission to access, and their specific permissions within each environment. 

Here’s another example from Port’s internal developer portal:

These permissions can also be seen at the team level, which becomes helpful when building developer self-service actions and experiences. All of these permissions can also be changed from within the portal, removing the need to jump from service to service. 

Onboarding challenge 3: Understanding the code and related software infrastructure

Let’s revisit our onboarding situation: you are brand new to your job and need to understand the code you are responsible for. You need to figure out:

• Where the code runs
• Which, if any, other microservices it relies on
• How the microservices are broken down
• Where to find descriptions of each microservice, if they exist, and their API specs
• Who is responsible for the other microservices your own service is calling

At this point, you’re probably laughing because there is no way a single person can remember the thousands of components that are necessary to build a modern website. Even with comprehensive, well-maintained documentation, services and dependencies change frequently enough that any manual documentation is usually immediately out of date. 

An internal developer portal provides a service catalog and blueprints, which add to the catalog by graphically demonstrating the relationships between interconnected services. When combined, the service catalog and blueprints provide new developers with a full, up-to-date list of every service the company uses to produce software, from staging and demo environments to their live production environment:

With these views in the portal, a new developer can understand everything they need to know to get started at once, saving time with managers and asking questions of peers.

These tools reduce the need for lengthy explanations and whiteboarding to explain the relationships between services and how they interact. They also eliminate the need to maintain separate documentation, as both the blueprint and catalog automatically ingest new services as they’re created and import the relationships between other related services, maintaining an updated graph of service dependencies and relationships in real time. 

Onboarding challenge 4: Providing new developers a task view and templated actions

Now that our new developer has received proper access to tools and understands the service they own and its related components, they still need to know where to start or what their tasks are.

An internal developer portal makes it easy to provide a dynamic view of a developer’s tasks so they can identify the next thing they need to do. You can create views in the portal that show the developer:

• The next onboarding task they need to complete
• Their open bugs
• Pull requests that are pending review (and how long they have been waiting)
• Ongoing incidents
• Key vulnerabilities affecting their service

These tasks are often called day-2 operations, which go beyond the initial phases of training and provide developers with a sense of autonomy, boosting their productivity and satisfaction. Providing day-2 operations in the portal also reduces time to productivity for new hires by making it obvious where to shift their focus.

Self-service actions also help abstract the complexity of internal processes. These can make it possible for developers to perform tasks or deploy resources following golden paths immediately, which is not typically expected of new developers until their first month.

Automated workflows, found in some internal developer portals, also enable you to send Slack alerts to managers who need to review work or chain tasks to automate onboarding entirely. You can also automate standards management, which may help a new developer build their knowledge of internal best practices when they’re coding for the first time.

Wrapping up

Onboarding new developers requires a ton of groundwork, well-maintained documentation and a repeatable process — all things that, under typical circumstances, are time-intensive and complex tasks to accomplish. An internal developer portal removes some of this complexity by:

• Defining the onboarding process: Once you’ve built an onboarding experience in your portal, you can reuse it for new developers or as a template for other types of onboarding experiences, driving standardization. This eliminates the need to maintain internal documentation or onboarding documents outside of the portal.
• Provisioning tools, access control and visibility: Developers can see everything they need to, but can only access and edit the services they own. 
• Displaying relationships between code and software infrastructure: The service catalog boosts autonomy and transparency, making it easier for new developers to orient themselves with the SDLC and take action as needed.
• Encouraging autonomy and productivity: Views within an internal developer portal tailor actions, services, tickets, tasks and more into a single place, making it easier for new developers to pick up work and become productive sooner and with less hands-on training.

If you’re not sure where to start with your onboarding experience, take a look at our ultimate developer onboarding checklist for some inspiration. If you’re not yet using an internal developer portal, check out our live demo and get familiar with how Port can help!