Most startups do not need a service catalog when they are small.
Everyone knows who owns everything. The person who wrote the service is in the same Slack channel. A question gets answered quickly. The list of systems exists in people’s heads, which works until it does not.
Then a customer sees an error. An alert fires. The engineer on call finds a dashboard but does not know who owns the dependency behind it. Someone asks, “Who owns this?” Five people are tagged. Nobody is certain.
That is when a service catalog becomes necessary.
Not because the company needs another tool. Because the customer needs a clear owner.
A catalog is not an inventory
The common mistake is treating a service catalog like an asset register. Add every application name, every server, every repository, and every dependency. Six months later, half the entries are stale and nobody trusts it.
A useful catalog is smaller. It starts with the production services customers rely on and records the information an engineer needs to act.
For each service, I want to know:
- What customer outcome does this service provide?
- Which team owns it?
- Who is on call right now?
- Where is the repository and deployment path?
- Which dashboard tells us whether customers are healthy?
- Where is the runbook for the first response?
- Which services can break this one?
That is enough to make the catalog useful on day one.
The important field is not the repository link. It is the owner.
Ownership is a production requirement
Every production service should have a named team that owns its reliability. Not a person who happens to know it best. A team that can make decisions, receive pages, maintain the runbook, and improve the service after an incident.
Without that, on-call becomes a forwarding service. The person who gets paged spends the incident finding someone else. The customer waits while the organization discovers its own structure.
This is not solved by an escalation spreadsheet. Escalation is what happens after ownership is already clear. The catalog should make the answer visible before the incident begins.
Keep the catalog close to the work
The reason many catalogs decay is that updating them feels separate from engineering work.
Do not make it separate.
When a new service is created, add its catalog record as part of the production-readiness check. When the on-call rotation changes, the catalog should reflect it. When a service is retired, remove it. When an incident exposes a missing runbook or unclear dependency, fix the record alongside the technical follow-up.
The more the catalog can pull from the repository, deployment system, paging tool, and observability platform, the less manual upkeep it needs. But automation is not the point. Trust is.
An engineer should be able to open a service record during an incident and believe what they see.
The catalog and the portal
The service catalog is the source of truth. The developer portal is the front door.
The catalog says who owns the service and how it runs. The portal gives an engineer a safe way to use that information: see health, find a runbook, review a change, deploy, roll back, or page the right team.
Build a beautiful portal without a trusted catalog and you have made confusion easier to browse.
Build the catalog first, keep it small, and make ownership real.
A service catalog is not documentation. It is a public promise that someone owns the customer outcome.