Get a Health Score & Auto-sync Your Docs With the Swimm and Compass Integration

[#1]

A healthy codebase is a well-documented codebase, and we invite you to explore how Compass integration with Swimm allows you to monitor the health of your documentation and enforce consistent documentation policies. Continuously.

What is Swimm?

If your organization is using Swimm, you’ve already experienced the benefits of code-coupled, Continuous Documentation. For those not yet in the Swimm of things, here’s your chance to discover how Swimm’s Continuous Documentation platform keeps your code, documentation, and dev teams in sync.

Swimm helps dev and engineering teams create documentation that is coupled to the code itself. Swimm verifies your documentation with every Git commit, and you are alerted whenever the code referenced by the documentation has changed. Even better: In most cases, Swimm’s GitHub App can automatically update the documentation for you using our Auto-sync algorithm. Features such as Swimm Smart Paths and Swimm Smart Tokens allow you to connect your text to your codebase and docs which creates a fluid reading experience – while ensuring your documentation stays up to date.

Adding the Swimm app to Compass

Compass centralizes your distributed architecture in a single, unified developer experience platform that helps teams collaborate and apply best practices at scale. Swimm’s integration enables teams to navigate documentation across the entire component catalog, flag outdated documentation, and review the documentation health of all your components at a glance with the Swimm Documentation Status scorecard.

Install and configure the Swimm app directly from the Apps tab in Compass.

Once the app is installed, click Configure to scan all your components for those linked to a GitHub repository.

From there, you can add a link from each component to its Swimm documentation and track its documentation status. Or you can do it all in one fell swoop by clicking Connect All Repositories. Have a repository that’s not yet linked to Swimm? Just click Start Documenting to get it connected.

Tracking documentation status

The Swimm Documentation Tracking component uses the Swimm GitHub app to monitor repositories (so be sure this app is installed on each repository you want to track in Compass). Whenever a pull request is merged to the repository’s main branch, Swimm analyzes the codebase for required documentation changes. The number of outdated documents is reported as a metric in its Compass component.

The Swimm Documentation Status Scorecard

For a high-level overview of the documentation status of all your components, take a look at the Swimm Documentation Status Scorecard (available from the Health tab in Compass). Components with up-to-date documentation show 100%, while those with outdated documentation show 0%. Use these insights to dig deeper and follow up with the relevant team leads to ensure compliance with your organization’s documentation policies.

How do I get started?

If you haven’t yet adopted Swimm as part of your team’s development workflow, it’s easy to get started. If you’ve already got Swimm, simply install the Swimm app from the Apps tab in Compass and check out Swimm’s documentation site for additional information about Swimm's Compass app.

Our team at Swimm is proud to be an official Compass Integration Partner and to be working together to change the workflow for devs. Sign up for Swimm and stay tuned to Swimm’s Slack Community Channel and watch for enhancements to the app coming soon!