Adopting Backstage - Documentation and Support

This is the first in a series of posts aimed at helping organizations to adopt Backstage.

Making Backstage Easier for New Users

Imagine opening Backstage for the first time, searching for a service, and finding… nothing. How do you even search properly? You’d need to understand concepts like entity kinds, types, and ownership.

And if you can’t find the entity, how do you add it? This requires knowing your organization’s ingestion patterns: Do you need a YAML file in the code repo? Or do you manually input the URL into the import flow? Without internal support or clear, beginner-friendly getting started documentation, this process can feel like a maze.

Backstage isn’t always intuitive, especially for new users without internal support or clear documentation. Most available open source documentation is aimed at implementers, not end users. It’s often generic, overwhelming, and assumes you’re using GitHub as your SCM system. So, what can you do to make Backstage easier for your team?

How to Simplify Backstage for Your End Users

Invest in User-Friendly Documentation

For Backstage to succeed in your organization, internal getting started documentation to help users use Backstage is a must. This documentation should be front and center for new users, which might mean putting it in an existing documentation platform even if your goal is to eventually move all docs into Backstage’s TechDocs. You can use the Homepage plugin to highlight certain top level info for new users including a preview card for your getting started docs in TechDocs.

Your getting started docs should open with a clear intro to what Backstage is and how it helps. Include simple examples of its core features, remembering that many new users won’t even know what an internal developer portal is meant to do.

As well as have a intro page in your internal documentation explaining it you could also publish a blog post introducing IDPs to your engineers.

### Internal Developer Portals
An Internal Developer Portal (IDP) is an application which is designed to give our developers easy access to information and commonly used workflows. Its goal is to reduce context switching and toil for developers by providing a “single pane of glass” that helps to improve productivity, reduce duplication of effort, and foster a more cohesive and efficient development environment.

An IDP is a place to find information about the software we build and use, the teams who build that software, and the API specs, code repositories and documentation associated with that software. It also typically provides self-service automation scripts for common tasks like creating applications or making changes to infrastructure, and scorecards to help ensure that software is adhering to best practices.

### What is Backstage
Backstage is an open-source platform for building developer portals. It was originally created by Spotify to manage and streamline their complex microservices architecture and was released for public use in 2020. 

**Key features of Backstage include**:
- Software Catalog: A centralized listing of all services, providing an overview and allowing easy management and discovery.
- Software Templates: Streamlined processes for setting up new projects and services with pre-defined templates.
- Plugins: Backstage is extensible with plugins to integrate with various tools and services used in AstraZeneca.
- TechDocs: A documentation site generator that converts Markdown files into a browsable documentation site.

Backstage aims to improve developer productivity and collaboration by providing a single, cohesive interface for all development-related activities.

Identify key user journeys and craft your getting started content around them:

• Why would a software engineer or product manager initially visit Backstage?
• What are they trying to accomplish?
• What problems could Backstage help with?

Talk to teams who are just onboarding or align these journeys with company-wide initiatives. If, for example, you see the Scaffolder as a high-value feature, start with docs explaining how to use it and how to modify templates.

You could create these docs in TechDocs and link them from wherever engineers currently go for org-level documentation or just create them in existing documentation systems like Confluence.

Ensure they are searchable by including the right keywords in titles and descriptions, whether hosted in Backstage or elsewhere.

Lastly, publicise these docs as much as you can - get a few blog posts out on any internal news distribution channels, ping organization wide channels with the link and a short teaser description (we’ll be writing a more detailed post about internal marketing very soon with a bunch of resources for you to use).

Create a Dedicated Support Channel

Establish a clear support channel—like a Slack or Teams group—where users can ask Backstage-related questions. This not only helps with adoption but also builds a community where knowledge is shared and best practices emerge.

Pin relevant internal and external docs in these channels to avoid repeated questions. Support channels are also a great place to identify gaps in your documentation, allowing you to improve onboarding and make it as self-service as possible.

You could even nominate Backstage champions—advocates within your organization who can help answer questions and lighten the load on your Platform Engineering/DevOps teams.

At Roadie, support channels with our customers have been essential to successful Backstage rollouts. While documentation is the first line of defense, having a place for follow-up questions is key to encouraging usage and reducing friction for busy engineers.

By streamlining these two areas—user-friendly getting started documentation and a dedicated support channel—you’ll make engaging with Backstage a smoother experience for your team and boost adoption.