Swimm is working hard to change how documentation is approached by dev teams. We’ve found that notifications create a sense of greater visibility and transparency around documentation and are an effective, simple way to stay apprised of updates being made to the codebase and corresponding documentation.
Since context switching is a time sucker, we’ve made our notifications useful, non-intrusive, and configurable. The ideal notification lets you know something has changed or facilitates an action. With a single click in our in-app menu, docs can be assigned, users can be approved or invited, and doc changes can be quickly reviewed.
Email, Slack, and In-app notifications
We’ve integrated three important channels dev teams use every day: email, in-app, and Slack. To stay in the loop for your workspace’s docs, Swimm notifications are contextual and native to the channel where they’re received, and we’ve tailored each notification to each destination.
Email notifications: Email notifications are short and consistent, allowing you to configure your email client to file and notify as you need.
Slack notifications: Slack notifications show up as direct messages from Swimm’s Slack integration.
In-app notifications: There’s a bit more depth to our in-app notifications because that’s where our product capabilities reside. The interface is familiar and intuitive, with:
- A red notification indicator on the bell icon at the top of the screen indicates that there are unseen notifications
- A red dot on the left indicates that the notification has not been seen.
- A white background indicates the notification has been clicked.
- A blue background indicates the notification hasn’t been clicked.
In-app notifications are silent, non-intrusive, and never disappear.
Configuring Swimm doc notifications
We prioritize code and documentation equally to ensure there are mechanisms for developers to create and monitor documentation.
At Swimm, there are five configurable circumstances for which we send notifications:
- A doc is assigned to the user
- There’s a reaction on a doc that a user contributed to
- A watched doc is updated in the default branch
By default, we also send notifications when: (1) someone requests to join a documentation workspace, (2) a user is invited to join a workspace, and (3) when Slack is installed in the workspace by an Administrator and all workspace users receive this notification.
How to configure your Swimm notifications
Swimm users can configure their notifications in a visual interface in their “User Settings” panel within the Swimm web Swimm web app.
The notification user interface is straightforward. We present the three notification types in a point-and-click matrix with the three notification channels.
- If the box is checked, you’ll receive a notification.
- If it’s unchecked, you won’t.
Notifications appear quickly, just seconds after any event occurs. You don’t have to click “Apply,” and the configuration changes occur instantly.
Watching your docs to know when they change
As subject matter experts in a codebase over time, developer expertise soon leads to code ownership, which makes changes to dependencies, architecture, or even variable name changes important to track. Because Swimm’s documentation is code-coupled and Auto-synced, it’s a nice convenience to decide if you want to get notified about when a doc changes.
Watching a doc for updates is as simple as clicking the “Watch” link in Swimm’s right-hand sidebar.
When there’s a documentation update, notifications are sent to anyone watching. Both the in-app and Slack notifications provide links to the watched doc.
In-app notification
Slack notification
Giving and receiving thanks for docs
Swimm has made it possible to acknowledge other teammates for the documentation they’ve created.
So if a reader wants to give kudos to a doc’s author, you’ve got a dropdown menu with a few options:
Great Doc, Time Saver, and Valuable Insights.
Once the reader sends thanks, the in-app notification tells the author who sent thanks and provides a link directly to the relevant doc:
And in Slack, the link to the relevant doc is also included:
Bottom line
We designed Swimm notifications to allow you to determine what they want to receive and how they want to receive it. You can control their preferences easily with no fuss and a single click.
When we add more integrations, it will be just as easy. We’re Swimm users ourselves, so these notifications are the ones we found most useful. If you have different notifications you’d like to see, just let us know in our Community Slack Channel.
Sign up for Swimm, or if you prefer to take Swimm for a spin with a tour first, we’d love to give you a product demo so you can see these notifications and all of Swimm in action.
