Course contentsShow
← Cloud and Infrastructure
Lesson 2930 of 2,98964. Platform EngineeringFree lesson

TechDocs for Documentation

Integrating docs-as-code with Backstage TechDocs to keep documentation alongside service definitions.

TechDocs for Documentation

You'll learn how to integrate documentation-as-code with Backstage TechDocs so your service documentation lives alongside the services themselves, ensuring docs stay fresh and discoverable.

The Core Idea

TechDocs is Backstage's built-in documentation system that treats documentation like code. Instead of separate wikis or outdated PDFs scattered across shared drives, TechDocs lets you write documentation in Markdown files that live in your service's repository. When services are registered in Backstage's Software Catalog, their docs are automatically discovered, built, and published right in the developer portal.

Think of it like a restaurant menu that updates itself whenever the chef changes a dish—no more "sorry, we don't actually have that anymore" moments. Your documentation lives in the same Git repository as your service code, versioned together, reviewed through pull requests, and automatically deployed alongside your services.

How It Works

TechDocs uses MkDocs under the hood to build static documentation sites from Markdown files. You add a mkdocs.yml configuration file to your repository, organize your docs in a /docs folder, and reference the location in your service's catalog-info.yaml file.

When developers browse your service in Backstage's Software Catalog, they click the "Docs" tab and see beautiful, searchable documentation that's always in sync with the current version of the service. No hunting through outdated Confluence pages or guessing which Google Doc is the right one.

This "docs-as-code" approach brings all the benefits of version control to documentation: history tracking, peer review, automated testing for broken links, and automatic deployment through your CI/CD pipeline.

Key Takeaway:
TechDocs integrates documentation directly into Backstage by treating docs as code—keeping them versioned, reviewable, and automatically published alongside service definitions in your Software Catalog.