I just improved my code documentation using Swimm.
Bad code documentation? Whatever Swimm will make it more knowledgeable and speedier.
Traditional document management systems have failed software engineers, and it is time for a new way.
Does Swimm use Docs-as-Code to provide developers with the help they need?
Is it the most recent Notion or Confluence?
The modern software development process is a weird throwback.
On the one hand, we’re using reducing tools and technology to construct large and powerful systems speedier than ever before.
On the other hand, when it comes to code documentation, we continue to use the same old methods while expecting different results.
Developers surely deserve better, but how do you improve documentation as a process?
Let’s speak about it, with a particular focus on Swimm, a new documentation/knowledge management system that champions the notion of Continuous Documentation.
Why Are Developers Losing Hope in Documentation?
First and foremost, why are we even discussing documentation?
We already know that it has a high perceived value.
Sure, documentation is difficult, but if we all chip in and document everything, there should be no problems, right?
Not exactly. As you will see, it is the process that is the issue, not individual effort and passion.
Any genuine solution would need more than simply elbow work.
In my seven years as a professional, I’ve worked with a wide range of clients and on a variety of teams.
But the horror stories have always been the same:
- There is no matching documentation. Instead, you’re advised that getting more features out faster is more important, and that “excellent code documents itself!”
- Docs are never enough to get you started with a new codebase. When you ask about a task, you are sent to a weirdly titled document in the business Google Drive.
- Jobs are marketed as “High Documentation” settings, however, this means they have a Confluence graveyard of outdated design documentation and nothing on how to set up and use internal dev tools.
- “Documenting new authentication endpoints is not yet a priority. Use the V1 docs we have hanging around someplace and ask for help in Slack.”
A thousand paper cuts mean death.
Would you believe documentation if this happened again across different projects?
Would you go out of your way to write and maintain quality documentation knowing it will be nearly hard to discover, obsolete in a matter of months, and valuable project-specific expertise lost with staff turnover?
“Documentation” Isn’t a Damn Thing
You can create as many tools on top of the present process as you want, but it will not help.
Here’s the secret that most folks seeking a solution never seem to discover.
Modern software development needs highly specialized skills that grow with domain experience.
This experience includes not just language and dev tool expertise, but also how to approach and solve unique, domain-specific challenges with limits that may not be immediately clear.
This is why documentation can never be a single “Superman” object that, once produced, fulfills every single knowledge need.
This is why the new system of documentation used by companies will not get you there.
Forcing the problem ultimately results in confusing documentation.
It’s either too wide or too limited to be useful, and it’s naturally difficult to document, manage, and canonize — making it readily outdated and broken, with just brief local knowledge left.
Instead, you should build more focused, structured documentation that directly mentions areas of your code and is written, saved, and updated together with it.
Which connects us to Swimm.
Swimm — Trust Winning in Documentation
Swimm focuses on making code-coupled documentation simpler to produce, manage, and locate across teams and repositories, with a rich-text editor and Markdown improved with code snippets.
They also feature Slack and IDE interfaces (Jetbrains and VS Code) that allow you to see local previews of your docs even when you’re not connected to the internet.
But, before we go into Swimm, let me express my own opinions:
- I’m not interested in another Notion or Confluence solution combined with another Bitbucket and Jira. I’m tired of technology developed on top of the current ways companies handle documentation.
- In general, I love the Docs-as-code approach, however…
For that, I can simply use a normal self-hosted, battle-tested ReadTheDocs solution. It must provide something extra. - Nothing turns me off more quickly than being vendor-locked.
- If I have to upload code directly to the servers of a SaaS, I may need to approve it with Legal first, which may slow down my documentation efforts and leave me wondering if it was even worth it. So that’s out of the question.
How does Swimm do in light of these requirements? Here are some of my main points.
How to Setup Swimm
If you wish to use Swimm, you must first create an account and connect your GitHub repository.
The process is simple, but it is presently limited to GitHub. However, I believe support for more platforms like GitLab and BitBucket is on the way.
Obtaining the Swimm Github App is also technically optional, but I highly advise you to consider it as important as, say, using strict mode for TypeScript development.
You’ll understand why soon enough.
Swimm’s privacy and security policies are excellent. They are SOC 2 and ISO27001 compliant, and your GitHub Auth Token and code are never transferred to or kept on Swimm servers.
The app leverages GitHub OAuth and requires just access to read your repo, assess changes regularly, and save the documentation you make in a separate.swm directory.
💡Swimm does need to know which Organizations control the repos you’ll be working on if you’re a member of one, so it may provide individual repo permissions inside it.
When documentation is code-coupled, it is simple to provide structured, focused documentation.
The first thing that strikes me is how you write documentation in Swimm.
Linking your GitHub repo provides more than just an authentication solution; it also allows you to refer to files in your repo directly.
…or any code discovered anywhere in it. Variables, functions, and even complete code snippets can be used.
More importantly, because it all starts with code, this documentation is exceedingly simple to produce and show with Markdown, diagrams, and photos.
Documentation — in the IDE.
So… yep. Swimm makes it simple to produce decent documentation, but it’s only a band-aid solution if I still have to hunt around in a thousand different locations to find it.
What if I could keep the documentation right next to me as I code?
Without the need to Alt-tab to Confluence, Wikis, GitHub, and Slack?
However, the Swimm IDE Marketplace reminds me that support is on the way.
Lovely!
Swimm’s ‘Auto-sync’
Writing strong documentation is simply one part of the process.
How do you ensure that it is always up to date?
To demonstrate, I’ll return to my IDE and update some of this code (such as changing the timestamp property to a more human-readable version) before committing it.
Overall, Swimm provides a simpler and more feature-rich approach than classic docs-as-code systems.
Playlists make information sharing easy and fun.
Playlists are a fantastic concept that has piqued my interest in terms of prospective applications.
They are also essential for staff onboarding. Playlists may be used to preserve ephemeral information — optimization hacks, tips and tricks, legacy code peculiarities, shortcuts, and so on — to ensure that anything not covered in canonical documentation isn’t lost when experienced personnel leave.
These Playlists are also markdown files that reside in your repo.
And, like with standard Swimm documents, they are maintained Auto-synced and up to date.
The Era of Continuous Documentation
This brings us to the end of this review.
Hopefully, you’ve realized that, while documentation is commonly regarded as laborious, manual work in the software development industry, it doesn’t have to be.
It’s about working smarter, not harder.
It is an issue of new documentation paradigms, not new technology built on top of what has previously failed developers.
Swimm isn’t perfect, but it’s the closest anybody has gotten to comprehend how the process of knowledge acquisition differs for modern software development, as well as how its requirements alter.
Swimm’s paradigm of code-coupled, Auto-synced Continuous Documentation, which considers documentation as first-class citizens alongside the development process itself, is the aid developers have deserved and longed for, since the beginning of time.
Swimm can be tried out here.
Don’t forget to follow me to keep me positive.
Sayonara, see you all in my future post.
