How to create a service catalogue

A comprehensive service catalogue is the only way organizations — especially at scale — can keep track of all of the services and how they depend on each other. As teams develop new services continually, in parallel, there has to be a way to keep track. Service catalogues are also a place to keep track of all the relevant information an engineer would need during an incident in one place. That information should include a link to the run book as well as who the service owners are and how to contact them.

Service catalogues are also a way to keep track of maintenance tasks and tech migrations — tracking which services have been updated to a newer platform, for example.

We’ve written about the need for a new approach to service catalogues before, but wanted to share some basic best practices for creating and maintaining service catalogues.

A good service catalogue should make it easy to locate all of the critical information teams need to respond during an incident. It will also help new team members get up to speed and understand how the organization’s services are related to one another. Here are some best practices on how to make sure the organization’s service catalogue is as useful as possible when it’s needed.

Keep it up-to-date

The biggest challenge for most organizations is keeping service catalogues continually up-to-date. Service catalogues are dramatically less useful if they’re outdated — if the contact person has since left the company, the information is worthless.

The only way to consistently ensure that a service catalogue is up-to-date is by leveraging configuration as code to discover new services automatically. A tool like effx that not only pulls information directly from services but also reminds team members to update information that can’t be pulled from the code also increases the likelihood that information like service ownership and contact information is updated.

Complete but continually evolving

Service catalogues are never ‘complete’ because they become out-of-date the minute a new service is deployed. It’s better to think of them as continually evolving but with information that is as-complete-as-possible at any given moment. There shouldn’t be any fields with missing information in the catalogue.

Easily searchable

Lastly, service catalogues should be as easy to search as possible. The search algorithm should be flexible, so that a user can search for a service’s name or for its function. The service catalogue should also allow searching by team or individual.

The key to creating searchable service catalogues is thinking through the reasons someone might need to search the service catalogue and considering what information would and would not be available in each scenario. The name of the service, for example, would often not be obvious, so the ability to search by the function the service performs is critical.

Common mistakes

The most common service catalogue mistake is failing to keep the catalogue up-to-date. Unless the process is managed automatically, it’s nearly impossible to get all the engineers in an organization to manually update a spreadsheet. Service catalogues are an organizational tool, designed to help individuals and teams easily find information about services that they don’t work on themselves. Getting service catalogues right really depends on full compliance from the organization. Without a tool to manage some of the process automatically and remind teams to update the rest, it’s hard to get the kind of organizational consistency that’s important to ensuring that service catalogues stay up-to-date.  

Using tools like effx to automatically keep the service catalogue up-to-date is one of the only ways to make sure the information engineer’s need from a service catalogue is there when they need it — which is often during an incident.

Joey Parsons

Joey Parsons

Founder & CEO of effx
San Francisco, CA