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.

Navigating Nuance: Beyond Literal Translation

The beauty of Backstage – and its core value proposition – lies not just in its technical features (the impressive scaffolding, the detailed tech docs) but also in how effectively it’s communicated. For non-native English speakers, especially those new to professional software development terminology, a literal translation of “technical documentation” or “developer portal” can be incredibly confusing and, frankly, useless. It’s far more effective to learn the specific phrasing used within Backstage’s context – the terminology that defines its function and value. This isn’t about perfect grammar; it’s about adopting the language of a thriving ecosystem where precise communication is paramount for collaboration, efficient development, and clear ownership. Think about how you’d explain a complex system to someone who doesn’t speak your native language – you wouldn’t just throw around jargon!

One common area of confusion stems from the concept of “ownership” within Backstage. It’s not simply assigning responsibility; it’s establishing a clear chain of accountability for specific tech docs, scaffolder templates, and even entire entities within the catalog. Phrases like “entity ownership” are deliberately chosen to convey this focused responsibility. Similarly, understanding the difference between a “scaffolding template” and a “TechDoc” is crucial – they represent distinct stages in the documentation lifecycle. Using these precise terms avoids ambiguity and allows developers to quickly grasp the intended workflow. Don’t be afraid to ask for clarification if you encounter unfamiliar language; a quick question can prevent significant misunderstandings. The goal isn’t fluency, but effective communication within this specific technical environment.

Furthermore, even seemingly simple phrases like “refactor” or “upstream” carry specific connotations within the open-source and software development communities. While their literal meanings might be understandable, they’re often used with a particular cadence and expectation – for example, in Slack conversations regarding code reviews. Recognizing these subtle nuances is key to participating effectively. Think about how you would explain why something needs refactoring or where the changes should be pushed. These small details contribute significantly to clear communication and collaborative problem-solving.

# Example: Using `backstage` CLI to list entities with a specific tag
backstage entity list --tag "payments" --format json

This simple command, when discussed in a team setting, becomes more than just a technical instruction; it’s an example of utilizing Backstage’s capabilities and the associated terminology within a practical workflow. Learning these phrases allows you to not only navigate Backstage, but also actively contribute to its vibrant community.