More and more R&D organizations are implementing an Internal Developer Portal (IDP) – unified applications that centralize all tooling, software components, data sources, and documentation. Essentially, everything a developer needs to get the job done.
Today, we’re excited to announce that Swimm is an official launch partner for Spotify’s Backstage portal, a full-featured internal developer portal built by the Backstage experts at Spotify.
TechDocs by Backstage
TechDocs is a docs-as-code solution built directly into Backstage by Spotify. In fact, it’s the most popular Backstage plugin, accounting for 20% of all traffic. TechDocs enables developers using Backstage to create and discover technical documentation from the Service’s page in the Backstage Catalog.
The Backstage team built TechDocs following an internal developer survey. They found that one of the top challenges faced by developers was the struggle to find the technical information needed to do their work. There was no standard way for teams to create and discover documentation. Some teams used Confluence, Google Docs, or README files, while others created custom-built websites or used GitHub Pages. If developers needed an answer, they were forced to hunt through all these different sources without knowing whether the information was actually up to date.
Swimm and Backstage = Documentation that’s always up to date 🤯
Every developer will probably agree that one of the biggest challenges with technical documentation is keeping it up to date – and to quote the team that built TechDocs for Backstage, “it’s not an easy nut to crack.”
Currently, TechDocs surfaces when documentation was last updated, top 5 contributors, the support channel, owning team, and the number of open GitHub issues. The Swimm integration enables technical documentation to be kept up to date automatically as part of the CI process – finally bringing trust back to technical documentation.
This works thanks to Auto-sync, a patented algorithm that automatically keeps code snippets that live within documentation up to date. When a developer opens a PR, Swimm analyzes the diff to find all documentation that references the code, and in most changes we make the necessary updates automatically. Swimm only asks developers to intervene if a significant change is detected.
A ripple effect?
When we speak with different teams about documentation within their organization, one of the most common themes is that if developers write documentation, these docs tend to be high-level and limited in scope of how it can be used.
With Swimm keeping documentation up to date, devs have good reason to write extensive and in-depth documentation because they know it will remain relevant and discoverable. We hear time and again that up-to-date documentation contributes to creating a culture of documentation and knowledge sharing – ultimately improving developer happiness, experience, and velocity.
Wrapping up
We’re thrilled to announce our latest partnership and look forward to bringing the magic of up-to-date documentation to more and more dev teams. This is just the beginning, so stay tuned for more exciting announcements soon.
Interested in a consultation? Click here to set up a call.
