9.1.2-techdocs.md

docs/9-platform-engineering/9.1.2-techdocs.md

category estReadingMinutes exercises Platform Engineering 10 name description estMinutes technologies Enable Documentation for an Existing Entity This exercise instructs students to add the bare minimum amount of files needed for their Backstage instance to generate an MkDocs site and associate it with an entity in their Software Catalog. Extra credit is offered for studying Backstage's ability to search within TechDocs stored in the Catalog -- the basic setup we point students towards in this exercise can lead to a search-related bug which is valuable for understanding the different ways Backstage can be configured to manage TechDocs. 40 GitHub Backstage

TechDocs

TechDocs is Spotify's homegrown docs-like-code solution built directly into Backstage.

This solution is built on top of the docs like code approach. One central idea to this approach is that documentation should live with the code that it documents. This way if a developer can find either the code or its documentation, they can immediately find the other -- without having to go through any kind of rigmarole.

Backstage enables the docs like code approach by providing tools that can automatically generate an easy-to-navigate documentation website and associate it with one or more entities in a Software Catalog. This can be achieved in multiple ways -- for example, you can set up automated documentation with your Software Templates so that any Software Templates built on your Backstage instance will come with an associated docs website. You can also configure CI/CD to generate and publish TechDocs sites.

Exercise: Enable Documentation for an Existing Entity

While TechDocs can be used in a variety of ways, we will start with something simple.

1. If you haven't already, configure your Backstage instance to generate Software Catalog entities based on catalog-info.yaml files in a GitHub organization that you own.
2. Follow the Backstage docs to create and publish documentation for an entity in your Software Catalog.
3. Verify that you can visit a "Documentation" section for your entity containing a nicely formatted docs page.
4. Deep dive: Experiment with performing a top-level search of your Backstage instance for keywords contained in your docs. If this goes without a hitch, try stopping and restarting your instance, and immediately performing that search again. What happens, and why?

Deliverables

• What are some key aspects of the docs like code approach?
• How might an enterprise organization make use of TechDocs to manage documentation?