We’re big fans of eating our own dog food here, just like the President of Kal Kan Pet Food who is known to have eaten a can of his dog food at a shareholder’s meeting to demonstrate how good his product is.
But we’re not making dog food at Swimm – we’re helping companies create and maintain documentation. So we’re constantly using and testing our platform, enabling developers to create code-coupled documentation – and we are most definitely taking advantage of all of Swimm’s incredible features to make Swimm the best platform it can be for our rapidly growing community of users.
Here’s a sneak peek – a behind-the-scenes look at how Swimm uses Swimm.
Swimm onboards new devs with Swimm Playlists
A key mission at Swimm is to build better, stronger, more informed teams – and we use Swimm’s platform to meet that goal. So yes, as soon as we hire new employees, it’s our top priority to make the onboarding process as informative, easy, and seamless as possible.
So how does it happen at Swimm? Aside from having their desk setup, a laptop ready to go, and some nice Swimm swag, we get new devs up to speed with a dedicated, personalized Swimm Playlist inside their Swimm Workspace.
This method of using Playlists – collections of docs, links, Markdown files, and videos all gathered together – is a shift to “self-instructed onboarding” from the traditional “buddy system onboarding.”
This may sound like a small change. But actually, with a more self-instructed onboarding approach, instead of new employees needing to ask the team for help, Swimm Playlists create a faster onboarding experience – reducing the onboarding strain on the team. Plus, having the Playlist individualized to mention the new engineer by name helps create a more personal and welcoming onboarding environment which instills trust in the documentation.
Swimm tip:
Swimm Playlists are a commonly used feature amongst our growing community of users. This is a great place to start if you’re looking for a launching point for using Swimm.
Swimm uses Swimm for knowledge sharing
At Swimm, documentation is used throughout the entire development process, whether code is directly involved or not.
Swimm spotlights important code via IDE Extensions
Every dev at Swimm has the Swimm IDE extensions installed (available for VS Code and the IntelliJ family). With these extensions installed, we have greater visibility and accessibility to our existing code docs.
This means that if an engineer interacts with a documented piece of code, they will have a direct link to see that document – inside the IDE – without having to switch contexts. We use IDE extensions to show our “how to” docs at the right moment, warn about delicate code involved in a hot-fix, or add some information from a design doc – or some other product considerations.
Swimm tip:
At Swimm, we try to make our doc titles stand out to entice people to go in and read new updates.
Swimm uses notifications to discover interesting new documentation
At Swimm, we also have a Slack channel called Doc Recommendations that are connected to Swimm via our Slack integration. Every time a new document is added to our main branch, the entire Swimm team is updated. This gives visibility updates to everyone interacting with a specific repo, even if they are on a different team. It also makes it easy to learn something new, start a conversation about a new feature, and generally be aware of what’s happening in a repository.
New Doc Notifications on Slack is a quick-win Swimm feature.
Swimm never overlooks incident reports
While code-coupled documentation is a huge piece of what we do, there are also many things we interact with that might not touch code at all – like the UI of a system to monitor logs or scripts we’re running to set up an environment.
A good example is Incident Reports, a critical use case for adding visibility to our existing documentation. Everyone makes mistakes – our team at Swimm is very much included. At Swimm, we summarize incidents and add a snippet of the bug fix to the report, and this makes it easier to surface fragile code while working on it in the IDE. Swimm’s GitHub app does the same thing by helping reviewers and PR owners find relevant documentation to the code that is being updated.
Saving our Incident Reports as Swimm Docs also serves as a reminder to our team that bug fixes tend to be hacky and usually require a refactor.
Because, as we know, having documentation is only worth it if it could be found easily. If the documentation exists, but no one reads it, even when it could save them time/bugs, then what’s the point of having it?
Swimm tip:
Create documentation for every Incident Report. It’ll save another developer time down the road.
Tagging documentation
A new Swimm feature is tagging documents. You can add tags on each doc and filter your docs by tag in your repos. When a tag is created, you can use it across all of your workspace repos. You can also rename, remove, or permanently delete a tag from your workspace easily.
All you have to do is go into a doc and then, from the sidebar, hover over the tag. Then you click on the “…” menu to manage your options.
How Swimm has created a culture of documentation
By now, it should be pretty clear that we use documentation a lot at Swimm. Not only do we include documentation as a part of our Definition of Done for features, but we also try to use the tools available at Swimm to ensure everything – no matter how small – is documented.
Swimm encourages the documentation of interesting PRs using the Draft Doc comment feature
At Swimm, we use the GitHub app Draft Doc comment feature, which allows us to add all of our code changes into a new document. This feature shows up if Swimm’s GitHub app determines a PR is interesting – meaning there is a significant change that mainly adds code and doesn’t touch too many or too few files, etc.
We use the Draft Doc feature all the time because it’s a quick win for our teams: all that we have to do is to explain what the different code snippets do, order the doc in a way that tells a story, and remove any irrelevant information.
Swimm tip:
Install Swimm’s GitHub app to help your streamline documentation and keep everything up to date.
Swimm manages our tasks with Doc Requests & Doc Assignments
There are two other features that we use all the time here at Swimm: Doc Requests and Doc Assignments. Doing this makes it easier to remember to come back and improve documents we promised to revisit while keeping track of everything else we’re working on.
These two features help motivate our team to cross our t’s and dot our i’s. For example, when a new doc is needed or an existing one needs updating, we are diligent in assigning it to the right person or team.
We see the benefits of these two features in action every single day – and it’s made the creation and updating of documentation a completely normal part of our developer culture in building Swimm’s platform.
How Swimm keeps docs up to date
I’ll state the obvious great thing: working in Swimm means we have a lot of documentation for our codebase.
Are we done with documentation at that point? No, just as code is constantly changing, so are our docs.
But, there’s one thing that’s pushing us forward all the time – which is that we have up-to-date documentation of our codebase. It means we don’t need to guess if this is the latest version of a document or if there’s another link or another more updated copy somewhere.
Swimm takes advantage of automation features like Swimm Verify Check & Auto-sync
At Swimm, we keep things updated by using the GitHub app Swimm Verify Check. Using these features ensures our documentation is both up to date and stays bug-free when our code changes. We also make sure to have our automatic Auto-sync approval feature turned on, so whenever the change is simple, Swimm’s GitHub app automatically compiles an Auto-synced version of our documentation and commits it.
Auto-sync in action is a no-brainer. So at Swimm, we are Auto-syncing all the time.
Connect your plan and implementation by saving Design Docs in Swimm
Having up-to-date documentation is just one piece of the puzzle, and it works really well for code-coupled documentation.
But what about design documents – the documentation containing the design of our features? Not only is it a policy for us to document design docs in Swimm, but we also make a habit of asking for the implementation of a feature to be added to the design doc as code snippets.
Our use of Design Docs makes it easier for us to understand why a certain feature was built the way it was and makes it easier to share knowledge and collaborate across teams. Adding the implementation as a code snippet to the Design Doc also enables us to revisit our original design after implementing changes and guarantees that we document any small concessions made while implementing a given feature.
Development processes are better with Swimm
We’re hoping it’s clear at this point that our team at Swimm understands the pain of missing or outdated documentation. And this is exactly why we are working hard to spread the word about how Continuous Documentation is a winning move to make knowledge sharing part of the development process.
But let me assure you, that doesn’t mean we’re all documentation experts at Swimm. What we know is that creating and updating documentation is not about perfection or expertise. It’s about documenting what you know, what has happened, and why – and sharing it with your team so that they’ll be in the know too.
Because what we understand at Swimm is that continuous learning and sharing is a core value and priority.
Writing interesting docs to tell a story
And, of course, we can’t end this post without some tips on writing good docs.
Dry and super technical documentation tends to be overlooked (surely you can relate), so we try to make it more inspiring.
The most important thing we focus on when we write a document is telling a story through code.
- We do this by first adding code snippets and any images to a Swimm Doc.
- Then we make sure to think of a compelling title and start to tell the story that ties everything in the doc together as if someone were sitting next to us.
- Next, we have fun by adding a surprise gif or joke at the end for people who made it through the entire document.
- Finally, we try to be mindful of the length of the docs. We keep documents long enough, so they’re worthwhile to read but not too long to become cumbersome. Sometimes, there are cases when we need to split one doc into multiple pieces. When that happens, we create and connect each doc into a Swimm Playlist.
Bottom line
Being both a user and an engineer of Swimm is a unique position and makes my job really interesting. This is true for the company at large. By using Swimm in so many different ways, we get to collaborate internally, test features across various teams and get feedback in real-time while doing the meaningful work of making our product the best it can be for everyone who uses it.
It’s amazing to be part of a company that practices what it preaches. It’s been a game changer to be developers creating Swimm’s platform with documentation always being up to date as our standard. We see these wins of continuous code-coupled documentation in action every single day.
Now that you have the full scoop on how Swimm uses Swimm, we invite you to sign up for a 1:1 demo to learn even more. We’ll go over more details about how you can use Swimm, answer any questions, and walk you through our newest features.
