Finding your IDP: A comprehensive guide to choosing an internal developer portal

There’s a moment in every successful tech company’s journey when it hits an inflection point. The company has done all the work to show enough true value to its users, and now it has to also grow its services, infrastructure, and team to continue delivering that value. 

This is a great point to hit—it means that you’re really helping your customers and building something valuable—but it’s also a time that can be fraught with challenges.

As multiple services get spun off, the infrastructure becomes more complicated, and the team expands, the old ways of working are no longer effective. Suddenly, the information that engineers were previously able to hold in their head or find written up in a Notion doc is obsolete. Where a single engineer might have known every method or service when the company was smaller, they no longer know fundamental things about their own company and product. And yet, they’re expected to work faster to keep up with growth.

They need knowledge, and you need to give it to them. The best place for a company to store that knowledge is in an internal developer portal (IDP). Focused on enabling visibility, standards, and self-service capabilities, IDPs centralize all the information about your services and your integrations, giving you the ability to track and manage your service maturity over time so you know how you’re growing.

Other benefits of incorporating an IDP include: 

• Increased visibility
• Improved self-serve capabilities for developers
• Faster time to market 
• Better developer experiences
• Enhanced production readiness
• Widespread adoption of consistent standards
• Centralized access to information and documentation
• Automation that supports getting work done 

But how do you pick the right one for your specific needs? Well, it does come down to your needs. The various solutions on the market cater to different teams at different stages. So it really comes down to this—what’s the problem you’re trying to solve?

‍

What’s your problem?

Any organization, especially one that is growing, is going to have plenty of challenges to go around. At a high level, some of the key issues that a lot of companies face include: 

• A lack of development velocity: Development velocity refers to the speed at which a development team can deliver new features, fixes, or updates. A reduced velocity might indicate bottlenecks, resource constraints, or other challenges in the development process, potentially delaying product releases and impacting business outcomes.
• Poor developer experience: Developer experience encompasses the tools, environments, documentation, and processes that developers interact with daily, with the goal of achieving a flow or focused state. A subpar developer experience can lead to decreased productivity, increased frustration, and a higher likelihood of errors, adversely affecting the overall quality and efficiency of software development.
• Sprawl and fragmentation of services: As organizations grow and evolve, they often end up with a multitude of disparate services spread across different platforms and environments. This sprawl can lead to inefficiencies, increased complexity, and potential inconsistencies, making it challenging to manage and monitor the entire system cohesively. In addition, this sprawl can also be reflected in a lack of consistency around documentation, standards, and more.

In part, these challenges all feed into each other. Developers can’t work quickly because they can’t find the right information about services, and that ultimately leads to a poor experience.

Fully understanding which of these broader challenges are impacting your team will require taking a more granular look. What are the problems your engineers are grappling with each day? And how do they ladder up to widespread trends that could be addressed by an IDP?

Ask yourself: 

• Do your developers not know what services are available within your organization? 
• Do new developers have trouble ramping up during onboarding? 
• Are you struggling to get features out the door? 
• Can your developers get started on a new project quickly and independently?

To get a clear understanding of what your team is going through, consider employing the following tactics:

1. One-on-ones: If you are hearing the same issues in your individual meetings with each developer, that’s probably an area of concern.
2. Surveys: If you want to gather mass feedback, anonymous surveys will encourage more candid responses.
3. Retrospectives: Regular retrospectives after project phases or sprints to discuss what went well and what could be improved.
4. Metrics: When you are tracking metrics related to developer productivity, like bug rates, code churn, or time taken to resolve issues, high or unusual numbers might indicate challenges.

Once you have a clear sense of your current problem areas, you should also take a look forwards. What are the challenges you expect down the road as you launch new features and scale your offering? As you look for the right IDP, you’ll not only need to account for your current needs, but what you expect your business to need in the next two, five, and 10 years. 

The core features of an IDP

Now that you’ve identified your core problems, you can start to articulate what features and services you may need out of an IDP. What follows are some of the features you’ll likely see across the available solutions, the problems they’ll help solve, and how important they are.

Service discovery

Importance: Highest

This is the critical component of an IDP and what your developers desperately want, as it will improve their productivity and experience.

Your IDP should be the central repository for service information within your org, allowing different teams to have a hub where they can find out how they work with and integrate with the rest of the organization.

Some specific features that are important here include:

• The ability to automatically suggest new services through integrations and Git.
• The ability to register services through YAML and code-as-config implementations.
• Being able to manage service definitions through infrastructure-as-code solutions such as Terraform.
• Being able to populate and update services through APIs.

With service discovery in place, developers can focus on building functionality without a) having to communicate with each team independently, or b) not even knowing what services are available.

Note: services should also be enabled with service templates that make it easier for developers to spin up a new service. 

Maturity Modeling

Importance: High

As services scale, it becomes more and more important to build out standards, first team-wide and then org-wide. Maturity modeling is how you can do this, with your ops team taking the lead on making sure every team is producing the highest-quality code.

Some key service maturity features include the ability to define what maturity levels look like for you, the ability to make sure standards are applied across all services, being able to define validation checks across services, data, and code, as well as visibility. 

Maturity modeling won’t just help provide a good developer experience, it will also help prevent mission-critical issues like outages and breaches that can occur as a result of outdated software, infrastructure, and modeling.

Integrations

Importance: High

The number of integrations your team uses will bloom as your product scales. This can quickly become a problem as different teams use different solutions, and engineers don’t always have visibility into what integrations are available. Orgs end up double-paying for different solutions or paying more because they don’t understand the true usage in the org.

As you scale, you’re not just going to need to deal with your Git integration, CI/CD pipeline, and K8s integration, but integrations for code quality, observability, error tracking, ticketing, and security.

Understanding the integrations within an organization will help developers by providing them with the quick information they need to integrate existing products with their code, and also helps finance teams understand usage to keep costs down.

Documentation

Importance: Medium

Internal documentation is often an afterthought, but it’s critical if you want your organization to scale and evolve effectively.

You can document your code elsewhere (e.g. in the repo), but having central docs where your service discovery also happens improves the developer experience for your team and makes them more efficient. An IDP can help with this by automatically ingesting both your technical documentation and your API documentation directly from your codebase.

Time to value

Importance: High

This is one of the features that, by its nature, isn’t initially obvious—but it will become incredibly obvious if it doesn’t materialize. There is always a ramp up time for IDPs as you integrate your code, but you want your developers to see the value of it within weeks rather than years.

This comes from being able to quickly integrate the IDP into your workflow and catalog your services faster. This can only really happen via automation. If you have to manually add services to your IDP, it’s either a) going to take a long time, or b) not going to happen.

Cataloging also doesn’t stop at services. A good IDP will allow you to register and track:

• Infrastructure and related metadata
• Systems (aggregations of services) and related metadata
• Domains (aggregations of systems) and related metadata

It should also offer search and the ability to work with monorepos or microservice architectures.

Of note, many of the features listed above will be core for enabling engineers to self-serve and have a shorter path to contributing. 

The value-adds of an IDP

While most IDP solutions will have a core set of features, there are other characteristics and value-adds that may help you decide which makes the most sense for your team. 

Open source vs SaaS

Importance: High

This will seem like a minor feature until you make the wrong choice. Some solutions are open source, and this means you can build on top of them. If you have some highly specific needs, or your engineering team really wants this portal to be custom, an open source solution can work. However, the downside is that you need to invest a lot of time and effort in engineering the IDP before you get to see any value. It could easily be six months before you have any version of an IDP up and running (and you’ve had to dedicate a team to this, rather than have them on your product). You then have to maintain the IDP yourself.

A SaaS solution mitigates these problems. The IDP will be ready to use almost immediately, it will have all the features you need, and will be maintained and supported by the provider. Unless your needs are really unorthodox, SaaS will work best.

Flexibility

Importance: Medium

Even if you do go down the SaaS route, it’s important to still have an IDP that’s flexible to meet the different needs across teams. Each team likely has a variety of engineers and leaders that  simply do things differently. While your IDP will ultimately help you establish standards across the organization, it will do so in a flexible manner that doesn’t disrupt the developer experience. 

Pricing

Importance: Medium

Pricing is another important consideration. Depending on the price and pricing model of your IDP, it may become a barrier to scaling your organization. On the other hand, a price that’s too low can be a red flag. IDPs are for scaling teams and scaling teams need support, which usually aren’t part of a free plan.

IDPs typically offer seat- or usage-based pricing models to ensure your investment aligns with the solution's value proposition. Depending on your industry, you might also need to consider self-hosting the solution to align with regulatory requirements.

Developer experience

Importance: High

Developers are the most valuable asset at a company. The entire point of an IDP is to make them more valuable. You do that by improving the experience at your company so they can produce higher quality engineering in quicker times. DevX is how you do that—giving them the right tools to do their jobs and then allowing them to do that job.

Support

Importance: Medium

As you need flexibility in an IDP, you’ll also need support from your vendor to make sure you’re using the platform as effectively as possible. As we said with pricing, this might not seem too important to start, but as you grow and come across the edge cases unique to your organization, you’ll need support to help you use the IDP to its full capacity.

Reporting

Importance: Medium

Another benefit that won’t always be obvious, but will be a boon to your ops team, is reporting. This is especially when it comes to maturity, as you’ll need to understand how your team is using the IDP. Are devs interacting with it on a daily basis? Or are they never checking the dashboard and you need to ping them? Reporting can help with this.

Reporting dashboards, both for across the organization and on a team or group basis can help the ops team gain visibility into service maturity and service usage. Ideally, an IDP can also provide detailed metrics that can be exported to data warehouses for more analysis. It also helps if there’s a good way for the ops team to report maturity up the organization, to show improvements and ROI.

Automation

Importance: Medium

A robust IDP will have two avenues of automation. The first is a way to keep your teams up-to-date on what is happening with the codebase and what’s needed. This could be through automated Slack notifications or push notifications to alert team members to issues.

Secondly, automation is also key for keeping the IDP up-to-date based on changes in code. If it doesn’t have the former, things will get missed. If it doesn’t have the latter, the data in the tool will quickly become obsolete. 

Common IDP automations include the:

• Creation and generation of service code from templates.
• Creation and running of common operational tasks, such as deploying new environments.
• Creation of repos and opening of PRs for newly generated services.

Choosing the right IDP for your team

To help you select the right internal developer portal for you, we’ve put together a Notion template here to help guide your decisions.

If you want to get started with a no-code internal developer portal, you can get a free trial of OpsLevel now. You’ll have a complete and up-to-date catalog of your services and other components in minutes—no heavy lifting (or coding) required.