The Docs-as-Code Principle#

Documentation as code means treating documentation the same way you treat source code: stored in version control, reviewed in pull requests, tested in CI, and deployed automatically. The alternative – documentation in a wiki, a Google Doc, or someone’s head – drifts out of sync with the codebase within weeks.

The core workflow: docs live alongside the code they describe (usually in a docs/ directory or inline), changes go through the same PR process, CI builds and validates the docs, and a pipeline deploys them automatically on merge.

What Backstage Provides#

Backstage is an open-source developer portal originally built by Spotify, now a CNCF Incubating project. It serves as the single UI layer for an internal developer platform, unifying the service catalog, documentation, scaffolding templates, and plugin-based integrations behind one interface. It does not replace your tools — it provides a consistent frontend for discovering and interacting with them.

The core components:

• Software Catalog: A registry of all services, libraries, APIs, and infrastructure components, populated from YAML descriptor files in your repositories.
• TechDocs: Documentation-as-code powered by MkDocs, rendered directly in the Backstage UI alongside the service it describes.
• Scaffolder: A template engine that creates new projects from predefined templates — repositories, CI pipelines, Kubernetes manifests, and all.
• Plugins: Backstage’s extension mechanism. The community provides plugins for Kubernetes, ArgoCD, PagerDuty, GitHub Actions, Terraform, and hundreds of other tools.

Installation#

Backstage requires Node.js 18+ and Yarn. Create a new Backstage app: