Modern development practices often favor microservices or some form of functional separation for complex software. but overusing them can lead to significant issues. An excessive number of microservices can overwhelm an organization. Additionally, teams might use similar technologies but follow different standards, resulting in varied code styles that complicate collaboration across projects.

The core idea behind service catalogs like those of Amazon Web Services (AWS), Atlassian, OpsLevel, or the open source dev portal Backstage is to offer a tool that lists and helps manage all the services available in your organization. Having a place where you can discover your organization’s existing software catalog makes it easier to avoid duplicated efforts:

This article will help you understand a service catalog’s value proposition and core features, know when to use it (and when not), and be mindful of some common pitfalls and how to overcome them.

What Is a Service Catalog

A service catalog is a centralized place to look for a list of available software services. It should contain a detailed description of what each software component does in a standardized format. Common information to include is the component’s creator, the team it belongs to, standardized input and outputs, version, and anything else your organization considers valuable. The software catalog saves the documents describing each component or an external reference to where the document is, parses its contents, and then displays them:

Combining your service catalog with a templating engine gives you a self-service portal that can register every new software component created to the service catalog. Such a portal promotes better documentation and ensures ownership of the components doesn’t get lost.

Using a service catalog means that developers can refer to the catalog to see if their use case falls within the defined services. If yes, they can get started on their own without having to wait for a support ticket to be approved. New members assigned to work on a project don’t have to waste time finding the standard practices for specific use cases and then asking for help to verify that they comply with said standards. With a software catalog, the necessary security standards and guardrails should already be baked into the templates available to the users:

Why Use a Software Service Catalog

You’ve already learned about some of the major benefits of a service catalog:

• Better governance and documentation
• Better discoverability of the components since they’re registered back to the catalog

But it also offers deeper systemic benefits.

Empowering Devs and Ops to Be Proactive

Arguably, the most significant upside of a software catalog is the paradigm shift that comes with it: it empowers developers to take the lead in gathering the resources they need to create their products and get comfortable deploying their code.

At the same time, the job of a DevOps team becomes building and maintaining a set of tools that reduce the burden of IT support teams. Instead of jumping on a call to create a continuous integration, continuous delivery (CI/CD) pipeline for each developer who needs to deploy a new service, they focus on creating a robust template that provides developers with a ready-made repository that contains a pipeline to deploy their code.

When operations teams focus on the catalog instead of individual cases, they can cost-optimize the most used cases in the organization and ensure good monitoring and security for them.

Quality through Standardization

A well-maintained software service catalog makes the right way the default for new software components. Every time someone creates a new react component, their repository is set up to automatically include a documentation file in the format of the software catalog, a CI/CD pipeline file using standardized modules, and the infrastructure resources associated with the code are cost-optimized.

This gives you a degree of standardization that’s difficult to achieve without a software catalog. Each project requires fine-tuning, and the catalog does not cover some edge cases, but it dramatically improves the base quality of the covered cases.

These benefits explain the rise and popularity of Backstage, the most popular service catalog at the moment. Organizations like Spotify and Expedia use it extensively as their developer portal, while Fiverr uses Backstage to unify existing software utilities under a single roof.

The Challenges of a Software Service Catalog

Everything about service catalogs sounds excellent so far, but nothing in this world is perfect. Implementing a service catalog comes with some common pitfalls that you need to know to be able to navigate your way through them.

Adoption

Developers are humans, and humans resist change. One of the first challenges you’ll likely face is adoption. If developers are too set in their ways, they could take a while to use the catalog.

Outdated Documentation

Humans also tend to forget things or skip what they see as non-essential tasks, especially when working under tight deadlines or less-than-ideal workloads.

It is no surprise, then, that one of the most common issues with service catalogs is out-of-date documentation. These service catalogs show an entry for some software components that describes what it was several iterations ago, not what they actually is today.

Out-of-control Sprawl

A software catalog could also become so extensive that finding what you’re looking for is difficult. This can lead to duplicated efforts, which in turn leads to more entries in the catalog and so forth.

If a service catalog has sprawled out of control, it becomes very easy for people to leave dead services behind when they leave the organization. You could end up with a service catalog full of out-of-date components whose owners left five years ago. And that isn’t worth much to an organization.

Overcoming the Challenges of Service Catalogs

If your service catalog is going to be successful, you need to build on two non-negotiable building blocks:

• Leadership buy-in for dedicating sufficient resources to the service catalog’s maintenance
• A team that owns the platform

A software catalog is a product that requires maintenance and active effort to keep it usable. If your organization can’t dedicate an appropriate amount of effort to a service catalog’s continuous success, you’re better off not implementing one at all.

Once the resources and responsibility are established, the greatest ally of the team that owns the platform is automation. Define clear workflows for creating software components and use templating systems extensively to ensure every new component includes all the data relevant to the catalog. Create jobs in your CI/CD that automatically take the release comments and add them to the documentation available in the catalog. Connect your catalog to your organization’s directory (like Lightweight Directory Access Protocol or LDAP) and make sure that whoever is listed as the owner of a service is still an active user. Or make the last person who approves a release a co-owner.

If you’re paying for a managed software service catalog, you might not have to do many of these things. But if you’re managing a self-hosted or open source catalog, you need to develop your own scripts to keep the catalog healthy.

Even with all the automation you can think of, your software catalog will also inevitably need some manual maintenance. This is why clear ownership is crucial. You need to schedule some oversight, check the catalog’s accuracy, and train teams to ensure they do their part in keeping the catalog healthy. Good support from leadership helps here, too: teams are more prone to see training and engagement initiatives as a priority rather than an afterthought.

Has It Gotten Out of Control?

As much as a healthy software catalog excites people and helps them work faster, a poorly managed portal does exactly the opposite—it gets in the way of your team’s productivity.

If the health of the software catalog degrades significantly, it becomes immediately apparent. One of the first things you will notice is that developers no longer use it. Whatever documentation is there exists because it was automatically created. If asked, developers will tell you they can never find anything in there, and whenever they find something, it’s still so out of date that it’s useless.

To keep your software service catalog from becoming what it swore to destroy, you have to continue to invest active effort, implement the ideas explained here, and, most importantly, listen to the developers using it. Gather feedback and sentiment, and work toward delivering a product that solves the main pain points of your organization.

Conclusion

Service catalogs and developer portals are becoming increasingly popular for a reason. Implementing one successfully can significantly improve productivity, quality, security, and even developer morale.

However, the change toward a service catalog comes with challenges and risks. If your organization has never worked under a platform engineering paradigm, setting up a developer portal can be challenging. A self-service approach requires a change of culture—operations teams must trust the development teams and let go of some of their usual tasks. Developers must take a proactive approach to service discovery and release management. You also need a team to own your service catalog, and they need leadership backing and the resources to fulfill their role.

This article explained what a service catalog is and what its benefits are. It also pointed out common challenges to help you know whether your organization is ready to implement a service catalog and how to do so successfully.