English for Backstage Developer Portal

Backstage discussions revolve around a specific set of nouns for organizing engineering knowledge — catalog, entity, template — and teams new to the platform often reach for vaguer words like “page” or “service list” that don’t map onto how Backstage actually models software.

Key Vocabulary

Software catalog — the central, queryable inventory of every component, API, and resource an organization owns, populated from YAML metadata files checked into each repository. “Before we can generate ownership reports, every service needs an entry in the software catalog — right now half of them are missing.”

Entity — a single item registered in the catalog, such as a component, API, system, or user, each described by a catalog-info.yaml file with a defined kind and metadata. “That microservice isn’t showing up because its entity file is missing the spec.owner field — the catalog can’t register it without one.”

TechDocs — Backstage’s built-in documentation system that renders Markdown files stored alongside code into browsable docs sites, keeping documentation versioned with the service it describes. “Move that runbook into TechDocs instead of a wiki page — it’ll live next to the code and get rebuilt automatically on every merge.”

Scaffolder template — a reusable blueprint that generates a new repository with a standard structure, CI configuration, and catalog registration when a developer creates a new service. “Use the scaffolder template for new services instead of copying an old repo — it wires up the catalog entry and pipeline correctly by default.”

Ownership — the metadata field on an entity that identifies which team is responsible for a component, used to drive on-call routing, catalog filtering, and accountability in incident reviews. “The catalog shows this API has no clear ownership — that’s the first thing to fix before we can even page the right team.”

Common Phrases

• “Is this service actually registered in the catalog, or are we just assuming it exists?”
• “Does this entity have an owner set, or is that still pointing at a placeholder team?”
• “Should this documentation live in TechDocs, or does it belong somewhere else entirely?”
• “Is there a scaffolder template for this kind of service, or are we starting from scratch?”
• “What does the catalog say about what depends on this API before we deprecate it?”

Example Sentences

Explaining an onboarding improvement: “New services now start from a scaffolder template that automatically registers the catalog entity and sets up the standard CI pipeline, so nobody has to remember those steps manually.”

Discussing an incident retro finding: “The escalation was delayed because the catalog entry for that service still listed the wrong team as owner — we’re auditing ownership fields across the catalog this week.”

Describing a documentation migration: “We moved the deployment runbooks into TechDocs so they’re versioned with the code and reviewed in the same pull requests, instead of drifting out of sync in a separate wiki.”

Professional Tips

• Say entity rather than “service” when discussing the catalog abstractly — an entity can be a component, API, system, or resource, and the word choice signals which kind you mean.
• Push for accurate ownership metadata explicitly in onboarding discussions — stale ownership fields are a recurring root cause of slow incident response.
• Recommend TechDocs by name over generic “documentation” when proposing where content should live — it signals a specific, versioned, code-adjacent solution, not just another wiki page.
• Reference the scaffolder template when discussing new service creation — it’s the concrete lever for enforcing standards, more actionable than saying “we should have conventions.”

Practice Exercise

1. Explain what the software catalog is and what problem it solves.
2. Describe the difference between an entity’s kind and its ownership field.
3. Write a sentence explaining why TechDocs living next to code is an advantage over a separate wiki.