Maximizing productivity with internal developer portals

When a company starts developing software, much of the knowledge of building high–quality services may reside in a few people’s heads. While this may work at a small scale, it breaks down as the number of apps and services you’re building grows in both number and complexity.

The challenge then becomes: how do you bring new developers up to speed quickly and efficiently? And how do you smooth out common hurdles for all your teams?

DX’s CEO, Abi Noda, got together with Chris Westerhold from Thoughtworks to dig into these questions, focusing on the role of developer portals in boosting productivity. Developer portals tackle these exact issues. This article will explain a developer portal, why it matters, who it’s for, and how to get one started. We’ll also give you the highlights from Abi and Chris’s conversation, offering their insights into how developer portals can make a real difference.

What is a developer portal?

A developer portal is a single internal location containing everything internal software developers need to know about creating, designing, implementing, deploying, securing, and maintaining corporate software.

"The shift to cloud and microservices has necessitated a unified approach to manage the sprawling architecture,” says Abi.

A developer portal is often created and maintained by a platform engineering team whose job is to streamline and standardize the internal software development process. The developer portal will consist of various resources, including internal documentation, an API service catalog, health and quality service dashboards, and self-service tools related to service development, such as deployment templates.

What problems does a developer portal solve?

Centralizing scattered information sources

A developer portal addresses the issue of navigating through multiple sources, often between 4 to 6 different ones, to find necessary information for software development. This scattering of resources can significantly decrease productivity as developers spend more time searching for information than coding. By centralizing information, a developer portal makes it easier to access required resources, thereby enhancing productivity and streamlining the development process.

Standardizing inconsistent development processes

A unified approach across teams can make development efforts more varied and efficient. Each team might create its methodologies, leading to inconsistencies and confusion. A developer portal solves this problem by providing standardized practices and tools. A portal ensures that all teams follow a consistent development process, reducing redundancies and inefficiencies and fostering a more collaborative and efficient environment.

Identifying and addressing development gaps

Identifying and addressing gaps in the internal software development process can be challenging with dispersed resources and a lack of centralized oversight. A developer portal solves this problem by acting as a central hub. It quickly identifies and addresses gaps, making the development process more agile and responsive.

Developer portal vs. internal developer platform vs. service catalog

You may hear the terms “internal developer platform” or “service catalog” bandied around along with the developer portal. How do these differ from a developer portal?

An internal developer platform typically refers to all the tools developers use to create, ship, and maintain new services. IDPs integrate into a developer portal. Over time, the concepts of an internal developer platform and a developer portal tend to blend, with everyone referring to both as the developer portal.

A service catalog is a searchable list of software services within a company. It typically includes information such as service owners, API definitions, and documentation. A service catalog is often one of several features supported by a developer portal.

“A service catalog could be a spreadsheet,” says Abi. It could be in DataDog, NewRelic, something you’ve built, Backstage, or something else. A service catalog is a feature.”

Who uses developer portals?

Developer portals have several users:

• Software developers are the first and most important users of a developer portal. They will use it to initialize new services, deploy and monitor applications, and respond to service issues.
• Software development managers will often use a developer portal to find service health status, changes in flight, deployment status, developer productivity, happiness metrics, and service owners on other teams.
• Engineering leadership and platform engineers might use a developer portal to assess the productivity of their company’s development teams and identify issues that need to be addressed in the software development process.

However, having a clear leadership and management structure around your portal is critical.

“The last thing you want is a 40-person team running a tool like Backstage,” says Chris. “It should only be a handful, maybe six, that manage that central spot and then have these other teams contribute back to that in one way or another.”

Developer portal features

What capabilities does a developer portal offer? To put it broadly, it includes any feature that aids developers in their daily tasks. Typically, the following functionalities are the foundational ones most teams begin with:

Dashboards

These can include service health and monitoring dashboards, CI/CD pipeline build dashboards, and team productivity dashboards with statistics such as feature velocity, average time to close pull requests, and currently outstanding PRs,

Self-service tooling

Tools are available to perform essential development functions or request software development resources. These tools can facilitate a range of activities, including initializing a new service, creating a CI/CD pipeline, requesting cloud provider resources (for example, an AWS account billed to your cost center), initiating a security review, and logging incidents with other teams.

Service catalog

A searchable catalog encompasses all services published across the company. This service catalog empowers developers to discover standard services they can incorporate into their services, such as APIs for authenticating end-users or accessing other back-end data systems. Listings in the service catalog typically provide information about the service owners, OpenAPI definitions for the API service endpoints, onboarding information, and documentation.

Software catalog

A software catalog lists all approved third-party software packages, and tools developers can use in their work. It can include approved third-party libraries as well as command-line utilities. A software catalog helps companies prevent supply-chain attacks by ensuring that teams only use packages that have been examined and allowed for internal use.

Documentation and support

Besides documenting APIs via the service catalog, a developer portal will contain documentation for the company’s overall software development processes. This technical documentation can include the entire software development lifecycle (SDLC), service registration procedures, the security review process, Business Continuity/Disaster Recovery (BC/DR) guidelines, procedures for approving third-party software packages, and more.

Benefits of a software developer portal

A developer portal brings several essential benefits to large-scale software engineering operations:

Provides a centralized hub for corporate application development

Instead of digging up information and tooling on multiple sites, developers can find it all in one place.

For example, take the task of initializing a new service. This task may include several major subtasks:

• Provisioning a cloud account
• Registering a service and its associated Git repositories (e.g., for compliance verification, GDPR tracking, etc.)
• Initializing a service’s CI/CD pipeline
• Creating a team to receive alerts and requests in the company’s issue-tracking system

Managers might have to spread their tasks across four different internal websites without a developer portal. A developer portal allows for documentation, linking, and integration of these tasks into a seamless experience.

Simplifies onboarding

With a centralized developer portal, new developers have what they need to start app development in their new roles, including documentation of critical processes and standards and links to initialize new services and request cloud accounts.

Helps drive consistency in engineering standards

A developer portal standardizes the tools used in software development and encodes best practices centrally (e.g., building credential scanning and binary/script certificate signing into a templated CI/CD pipeline).

Enables better integration of developer tools

A developer portal that integrates various tools can help highlight their strengths and weaknesses, improving the developer’s overall experience. For instance, it may show that finding a service is easy, but logging a service request against the owning team is not. A developer portal can fill this gap by integrating the company’s issue-tracking system with its service catalog.

Improves developer productivity

Making tooling easier to find and easier to use reduces developers’ cognitive load. This enables them to spend more time-solving problems and less time fumbling around for tools and documentation, improving their productivity and overall experience.

However, a developer portal is not a DevEx silver bullet.

“A developer portal is an enablement tool to a developer experience journey,” says Chris. “And if you’re trying to stand up a developer portal and check that technology box, that’s a whole different thing than wanting to start and continue a journey around improving developer experience.”

Drives cost efficiency

Besides eliminating redundancy in tool and process development, a developer portal enables developers to ship new services and service features more quickly and with higher quality.

Implementing a developer portal

To implement a developer portal for your company, follow these essential steps:

Define your developers’ pain points

To enhance the developer experience with a developer portal, start by identifying your team’s main challenges. Consider what primary pain points they encounter, such as launching new services or reporting issues with existing ones. By focusing on these specific needs, you can equip the portal with features that directly address and alleviate these obstacles, streamlining workflows and boosting productivity from the outset.

Get leadership support and define ownership

No matter how you implement a developer portal, you must invest time, money, and engineers. You’ll need to calculate the return on investment and show your leadership how this project will save money and improve productivity. If you don’t already have a platform engineering team, this is the time to start a small team of four to six people who can lead this effort.

Select the right technology to meet your developer experience goals

When choosing a developer platform, pick platforms that work well with the tools you already use, like CI/CD pipelines and issue management software. Also, make sure the platform fits your specific goals. For example, DoorDash chose to prioritize a smooth, integrated set of developer tools based on what its developers needed, instead of starting with a service catalog like many others do. This shows it’s important to choose a platform that suits your team’s unique needs.

Implement

Once you have buy-in and a defined plan, set your platform engineering team to build support for your use case. Take an agile approach to your developer portal: don’t try to deliver everything at once; instead, focus on the feature most demanded by your developers.

Develop feedback loops and iterate

Once you’ve launched your initial developer portal, set up ways to get feedback from your developers on what’s working and what isn’t. Use this feedback to decide which features to prioritize next. Over time, you’ll craft a developer portal that addresses the major pain points of software development at your company—one that enhances developer experience and, consequently, improves productivity.

The relationship between developer portals and API management

Developer portals and APIs (Application Programming Interfaces) are intrinsically linked in the software development ecosystem, serving as complementary tools that enable seamless interaction between different software products and services. A developer portal acts as a gateway for developers to access, explore, and utilize APIs, offering comprehensive API documentation, API reference, usage guidelines, and often interactive tools like API key management and sandbox environments for testing.

Through these portals, developers, or API consumers, can quickly discover how to integrate and leverage APIs in their applications. Portals are indispensable for promoting API product adoption and fostering a community of developers. Essentially, while APIs provide the building blocks for creating versatile and interconnected software applications, developer portals offer the blueprint and tools needed for an API developer to assemble those blocks effectively, ensuring developers have the resources they need to innovate and expand the capabilities of their software solutions.

Best open-source developer portals

Backstage

Backstage, created by Spotify, has been embraced by many companies as a foundational tool for building their developer portals. It acts as a centralized platform for developers, offering them a consistent and efficient way to manage software development and operations.

Pros:

• Comprehensive service catalog: Backstage provides a powerful and user-friendly service catalog, making organizing and discovering internal services easier.
• Extensibility: With its plugin architecture, Backstage allows for extensive customization, enabling teams to tailor the platform to their needs.
• Community support: Being an open-source project, Backstage has a vibrant community that contributes to its development, ensuring the platform is continually improved and updated.
• Integration capabilities: It offers robust integration capabilities with a wide range of tools and services, enhancing its utility across different stages of software development.

Cons:

• Complex setup: The initial setup can be complex, requiring a significant investment of time and resources.
• Learning curve: New users might find Backstage’s extensive features and capabilities overwhelming, leading to a steep learning curve.
• Customization requires effort: While its extensibility is a strength, customizing Backstage to fit specific needs can require substantial development work.

Clutch by Lyft

Clutch is Lyft’s open-source platform that empowers developers and engineering teams to manage infrastructure effectively. Focused on extensibility and usability, Clutch aims to streamline operational workflows.

Pros:

• Focused on infrastructure management: Clutch excels in infrastructure operations, providing tools for resource management, auditing, and troubleshooting.
• Extensible architecture: Similar to Backstage, developers build Clutch with a highly customizable, plugin-based architecture that allows new features and integrations to be added as needed.
• User-friendly interface: It offers a clean and intuitive user interface, simplifying the management of complex infrastructure tasks.

Cons:

• Niche focus: Clutch’s primary focus on infrastructure management might limit its appeal for teams looking for a broader set of developer tools.
• Community and support: While growing, the community around Clutch is not as large or active as some other open-source projects, potentially affecting the pace of development and support.

Atlassian Compass

Compass by Atlassian is a modern developer portal that focuses on improving software development processes by offering a unified view of microservices and facilitating team collaboration.

Pros:

• Integration with the Atlassian ecosystem: Compass seamlessly integrates with other Atlassian products, offering a cohesive experience for users of Jira, Bitbucket, and other Atlassian tools.
• Microservices management: It provides excellent support for microservices architecture, making it easier to manage and collaborate on microservices across teams.
• Developer collaboration: Compass emphasizes collaboration, offering features that enhance visibility and communication among development teams.

Cons:

• Dependency on Atlassian products: While integrating with Atlassian’s ecosystem can be a strength, it might also limit flexibility for teams not already using Them.
• New and evolving: Compass is still evolving as a relatively new offering, which means it may lack some features and polish found in more mature platforms.
• Cost: While Compass itself is open-source, leveraging its full potential often requires integration with paid Atlassian services, which could increase overall costs.

Boost productivity with a developer portal

Every company has its unique process for developing services. Chris sums it up by saying: “Do it with your community, not to your community. The portal has to solve people’s problems.”

A developer portal gives new and existing developers a roadmap for creating and managing software applications. A well-built developer portal reduces the time it takes to find and understand developer tools and processes, boosting developer productivity, increasing developer satisfaction, and reducing time to market for new features.