Creating an effective software catalog

Are you putting together an effective software catalog for your engineering teams? Or is your catalog already stale by the time you finish updating it?

On the latest episode of Level Up, we delve into developing top-notch software catalogs and their essential role in scaling engineering teams. Ezra Cohen, OpsLevel's first-ever Customer Success Manager, joined us to share his insights on this crucial aspect of software management and the good, bad and ugly of the catalogs he has seen. We explore why cataloging is an essential engineering best practice, how to effectively catalog your software and what makes an efficient catalog. Plus, we will dive into OpsLevel’s evolution into a robust developer portal that brings you the power of a comprehensive software and service catalog.

 Join as we discuss: 

• The importance and multifunctionality of a catalog
• What makes an effective catalog, and how to get there
• Why YAML is a trap to be avoided

Want to try our full software catalog yourself? Find it here.

The importance and multifunctionality of cataloging 

Cataloging is important across myriad professional roles, but it’s especially important for engineering leaders, regardless of industry. While many companies rely on a graveyard of rudimentary and outdated spreadsheets, those who utilize modern, effective cataloging practices see widespread benefits in the effectiveness and efficiency of their teams.

It can be difficult to navigate systems that you didn’t build — tools that most businesses use many of. But cataloging allows you to organize, track, understand and access the different tools and software your teams utilize.

“A platform team might use a catalog to drive a change across the entire organization, while DevOps would use it to find out about specific metrics,” Ezra says. “There’s a bunch of different use cases within an engineering organization.”

An effective catalog can help solve and prevent many major problems across organizations, particularly when implementing organization-wide changes. It does this by creating standardization.

“Once you have a good catalog that's built, maintained, up-to-date and automated, a migration tool becomes so much easier. Then, you can automate in ways you couldn't before,” Ezra says.

What makes an effective catalog and where many go wrong

While there are many different characteristics that determine whether a catalog is good and effective, 

Ezra breaks it down into four major attributes. A catalog is effective when it is:

1. Complete in terms of having all entry names and associated data.
2. Up to date.
3. Convenient and easy to find.
4. Searchable.

Unfortunately, many organizations struggle to create catalogs and fall short of establishing systems that meet the table stakes of effectiveness. Fortunately, through experience, Ezra has noticed several patterns that can help organizations navigate these challenges.

According to Ezra, most organizations face one of two paths when working toward building an effective catalog. Companies either: 

1. Struggle with a technology problem. They have all the data; it’s just dispersed and unorganized.
2. Exist in complete chaos with little to no change management.

Don’t know which category you’re in? Ask yourself these questions: 

• How consistent is the naming of your systems across different tools?
• How consistent are your assets?
• Does this consistency apply to all users?

If you’ve answered yes, your business belongs to the first category — you have a technology or an automation problem that can be much more easily addressed.

However, if you laugh at the thought of consistency, you may have a much more complicated road to effective cataloging. But there is hope. 

“Understand that this will require some toil,” Ezra says. “You’ve got to pay down some organizational technical debt.”

When you move fast and grow quickly, it can be easy to fall into situations where corners are cut and consistency is sacrificed. Creating an effective catalog will help ease future developments and the implementation of feature releases, but it will require some elbow grease to create those systems and integrate them in a previously less-organized system.

That work begins with building a roadmap and dedicating time to manually cataloging, Ezra says. You can use automation moving forward and perhaps build systems that can retrieve certain types of data, but manual cataloging will be necessary for any previous data.

Dedicate time to clearly define:

• What you need to make a complete catalog
• Specific systems and data to gather
• Where that data will be found
• How that data will be stored and organized into a catalog

Next, go team-by-team and have them do the work needed to fulfill the roadmap your leaders designed. Often, a Platform SRE team will work with the various teams to support and encourage each team to compile everything necessary.

“It’s not easy and it’s not a week-long task,” Ezra says. “ But it pays off in meaningful ways in the short and long term.”

How to avoid the YAML trap

YAML is often thought to be a quick and easy fix for documentation and cataloging issues. You can simply ask each team to write and drop YAML files to synchronize. But according to Ezra, this is a trap and definitely not the ideal path to take.

“People like YAML because it’s not a spreadsheet. It looks like code,” Ezra says. “But it's not good, scalable work. It's not automation. It's not building value for your customers.”

While there is some value to using YAML, particularly when it exists behind a Git workflow, it is impossible to use YAML to build a scalable, valuable cataloging system that is automated. Therefore, it should only be used as a last resort when all other options have been exhausted.

When you opt to use YAML, you actually decentralize your database by distributing it across several different Git repositories, therefore assigning Git as the authoritative place for your catalog. This is inefficient and simply shifts access and consistency issues to a different platform. 

When working towards a scalable, affordable and automatable catalog, YAML is not an ideal solution and will ultimately lock you out of the potential for automation later down the line.

‍Ready to find a cataloging service that is scalable, eases processes and meets the needs of you and your customers? OpsLevel has the solution.