Swimm’s GitHub app helps developer teams create, maintain, and find documentation as part of the development workflow.
When our team at Swimm began designing Swimm’s GitHub app, we needed to identify the best moment to interact with users. We knew, for example, that running and notifying users on every open branch can be annoying, and we wanted to make the experience simple and enjoyable. Moreover, we understood that we had to find the window of opportunity for developers - the best time when software engineers were looking for checks, reviews, and comments.
Design of Swimm’s GitHub App
Our team at Swimm started designing the GitHub app integration in 2021, keeping in mind that most interactions happen during Pull Requests because it’s usually the last point the code can be verified before it is merged into the main branch and deployed. But it’s also the first time when software engineers push their code and mark it as ready for review.
The initial version of Swimm’s GitHub App ran our Swimm Verify check whenever a PR was opened or an open PR was updated. This allowed us to make sure the documentation on the branch would stay up to date so that code changes would not require an update to the documentation.
Continuously improving Swimm’s GitHub App
Since then, we have added quite a few capabilities and features. Today we’re covering Swimm’s GitHub app features one by one.
Accepting Auto-synced changes from GitHub
Swimm's patented Auto-sync algorithm analyzes what happens in your codebase. When Swimm Verify check recognizes Auto-sync documentation changes, users are notified via a comment on your pull request. You can then trigger a Swimm Commit by clicking the “Approve Auto-sync” button in the check, which accepts all Auto-synced docs from the GitHub App.
Automatic Auto-sync approval
We’ve taken the Auto-sync feature one step further. In the GitHub app settings, you can set up automatic Auto-sync approval. Swimm’s GitHub app will automatically accept Auto-sync changes, committing them to your open pull request in a dedicated commit. Clients rely on Swimm’s trusted patented Auto-sync algorithm to automatically update their documentation with this feature.
New doc notifications
Since tracking and locating documentation is challenging, we designed a feature for New Doc Notifications: you can set an alert on Slack or via email whenever a new document is created and merged to your main branch. This helps keep track of new documentation in your repo and allows you to invite other members of your organization to read and learn more about new documentation. We’ve found that this encourages a better overall understanding of the codebase.
Draft Documents from Pull Requests
We all know too well that documentation is usually an afterthought, or something completed after writing tests and making code review requested changes to your PR.
This is exactly why Swimm’s GitHub App analyzes your code changes, and when a Pull Request is interesting enough to document, we notify you with a comment and encourage you to create it. With a single click on the Review Draft in App button in our comment, you go into Swimm’s Web App. All the code changes from your Pull Request are added to a document, and all that’s left for you is explaining what the code does. There are no rules for how to do this, but ideally, you would want to arrange it in an order that tells a story.
Doc recommendations
When you change code that has relevant documentation, Swimm’s GitHub app recommends documentation for you to review. This helps users access documentation about specific code changes by alerting you to relevant documentation on PRs.
Here are a few examples you might see: a doc is recommended to you for your E2E testing guide whenever someone changes a covered test; the CI deployment documentation is recommended when someone changes a configuration script; a fragile piece of code changes, and you are alerted to documentation that references an Incident Report.
Swimm Verify on PR changes only
We created an option to run Swimm Verify only on files that are changed in the Pull Request.
Here’s why: because we know that sometimes things break on the main branch. Perhaps a merge conflict or two competing changes are going on simultaneously. And we know that this can happen with your documentation as well. While these changes might take some time to be fixed, they might otherwise fail our Swimm Verify check across your repository, even on unrelated Pull Requests. So we suggest that it is a worthwhile option to turn this feature on until issues with your main branch are resolved. This feature helps our clients avoid unnecessary delays.
Disabling comments
Our engineering teams work in a fast-paced environment; we move quickly, frequently break things, and always work on bug fixes.
Therefore, we designed Swimm’s GitHub app with an option to disable comments. This helps reduce the number of notifications that you’ll be sent during busy deadlines and crunch time. And then, of course, you always have the option to enable the comments again whenever you wish.
Integrations with other tools
Swimm partnered with Atlassian Compass - bringing Swimm to Compass’ ecosystem so that you can see your latest documentation status for all your distributed services from a single place. You can also use Swimm’s Compass Integration to link Swimm documentation to the Compass component.
Swimm is currently integrating additional tools to facilitate understanding the bigger picture of your software development status with your Swimm documentation included.
Doc hooks - coming soon
Getting recommendations for a relevant document to existing code is helpful. But what about newly added code? There should be a way to locate documentation in situations such as:
- When a new database migration is added → link to your database migration policy
- When the configuration file is modified → link to your environment variable update process walkthrough
- When a new record is added to your Infrastructure as a code setting → link to your explainer on how to verify it will be deployed correctly.
Our team at Swimm is currently working on solutions to these exact problems. We are testing an alpha version of a feature that will recommend a specific document when a certain file is changed or something is added to a folder. Stay tuned!
Top comments (0)