Backstage Weekly 42 - Tons of TechDocs improvements

The second Backstage Users Unconference went off without a hitch last week. More than 90 people showed up to talk about all things Backstage.

8 topics were discussed over the course of the 2 hour session. Each topic was proposed and selected by the attendees of the conference. Once the topics had been chosen, we divided into sub-groups for discussion.

The topics discussed included:

• keeping Backstage up to date efficiently,
• modelling systems and domains in Backstage,
• using the new homepage plugin effectively.

Thank you to all the people whose attendance helped make this event special. An Unconference is primarily a community driven experience, and last week proved that the Backstage community is powerful.

We plan to have a Backstage Users Unconference approximately once per quarter going forward. You can expect the next one to happen some time in July. We’ll announce here when the date is set.

Merged recently

Recent weeks have seen a flurry of activity around TechDocs, which we wanted to highlight in this issue of Backstage Weekly.

TechDocs is the feature which makes technical documentation available inside Backstage. Many of the recent improvements are covered below.

Auto add techdocs-core plugin

Now that #9556 is merged, you no longer need to manually add the “techdocs-core” plugin to every mkdocs.yml file.

While the techdocs-core plugin was technically optional, if you didn’t add it, some docs looked quite broken inside Backstage. We’ve seen a few instances where Roadie users have been confused because they forgot to list it in their MkDocs configuration.

This change, contributed by Roadie engineer Jussi Hallila, should reduce the friction for teams who are adopting TechDocs.

Styling improvements

A raft of styling and readability improvements have been merged. Readability is of upmost importance when you’re trying to convince teams to start using TechDocs.

Here are some of the changes:

• Fixes for tiny headers in documentation in #9569.
• Feedback for the user when they copy code snippets to the clipboard in #9833.
• Improved highlighting colors for diffs in #9476
• A collapsed TechDocs sidebar on mobile in #9493
• Styling improvements for the inline search box in #9766

Upgrades and refactoring

Lastly, tons of refactoring, bug-fixing and upgrading has happened. Hopefully these changes will go some way towards making the TechDocs Addons Framework easier to deliver.

There’s too many PRs to list, but here’s a sample of the work done.

• Common packages have been renamed, moved and cleaned up in #9952 and #9718
• Tests were added for the TechDocs CLI in #9546
• Broken inline search was fixed in #9333

That’s all for this week folks. Get upgrading, and start writing some docs!