A Service Catalog for Engineering Teams: Fields, Tiers and Upkeep

Split fields into required and optional so entries stay easy to write. Require these:

• Name and one-line description: what it does, in words a new hire would understand.
• Owner team and a contact channel: a team, not a person, so it survives departures.
• On-call or escalation path: a link to the schedule or a paging alias.
• Tier: how critical it is (see below).
• Repository and deploy location: where the code lives and where it runs.
• Runbook link: what to do when it breaks.
• Lifecycle: experimental, production or deprecated.

Add these when you're ready: dashboard links, the service's SLO, upstream and downstream dependencies, data classification, API documentation and the on-call escalation policy. A short required list gets completed. A long one gets abandoned.

Tiers turn a vague sense of importance into a rule that decides response and standards. Keep to three or four levels and define each by customer impact, not by opinion:

1. Tier 1: customer-facing and revenue-critical. Failure stops customers from using the product. Requires on-call coverage, an SLO, a runbook and tested backups.
2. Tier 2: important but with a workaround or delayed effect. Business-hours response, a runbook and monitoring.
3. Tier 3: internal tools and batch jobs. Best-effort support, an owner and a README.
4. Tier 4 or deprecated: scheduled for removal, with a shutdown date.

Tie standards to tiers so you don't write separate policies. A Tier 1 service gets stricter review and patching than a Tier 3, and your security questionnaire answers become easier because the tiers already say how each class is handled.

Store the truth next to the code. One small YAML or JSON file per repository, reviewed in pull requests, keeps ownership changes visible and versioned. A scheduled job then collects them into a browsable index, a generated page, a spreadsheet or a portal.

Avoid keeping the primary copy in a wiki or spreadsheet that nobody reviews, because it decays the day after it's written. Add a validation step in CI that rejects a missing owner, an unknown tier or a dead runbook link. If you later adopt a portal such as Port or Backstage, the same files import directly, which is why the format you choose now matters less than owning the data. The portal comparison explains that step.

Follow a short plan:

1. Agree on the required fields and the tier definitions in one meeting.
2. Inventory services from your cloud accounts, deployment pipelines and repositories. Expect to find some nobody remembers.
3. Assign an owner to each, and mark orphans for decision: adopt, hand over or retire.
4. Add the metadata file to every repository, starting with Tier 1 services.
5. Generate the index and share it in your engineering chat.
6. Turn on the CI check for new services only, then enforce on existing ones after a grace period.

Say you find 40 services and 6 have no owner. That's the most valuable output of the exercise, because unowned services are where incidents last longest.

A finished entry can be short. For example: the service name and a one-line purpose; owner team and chat channel; Tier 2; repository and runtime location; runbook link; dependencies on the billing service and the primary database; lifecycle set to production. Ten lines that a new engineer can read in a minute are worth more than a form with forty fields nobody completes.

Catalogs decay when nothing forces them to be right. Build in these habits:

• Review ownership quarterly, and after every reorganization.
• Make the catalog the source for incident tooling, so a wrong on-call entry causes an obvious failure and gets fixed.
• Check links automatically and flag entries not updated in a long time.
• Include the catalog in new-hire onboarding, where new engineers naturally notice errors.
• Reference it from your API versioning policy and your postmortem process, so each incident review confirms the owner and tier were right.