Code Documentation Is Broken

Modern software development is a curious anachronism.

On one hand, we're using bleeding-edge tools and technologies that enable us to build complex and powerful systems at a faster pace than ever before. But on the other hand, we keep relying on the same old methodologies when it comes to documenting code, while somehow expecting different results.

Developers deserve better then, surely, but how do you fix documentation as a process? Let's talk about it - with a focus on Swimm - a documentation/knowledge management system fresh out of beta, championing the principle of Continuous Documentation.

Why Developers Lose Trust in Documentation

Firstly, why do we even need to talk about documentation? We already know its perceived value is high. It is difficult to write, sure, but if we all pitch in and document everything, there won't be any issues, right?

Not quite. As you'll see, the process is the problem, not individual effort and drive. Any real solution would require more than just elbow grease.

In my seven years as a professional, I've worked with multiple clients, on multiple teams. The horror stories, though, have always been the same:

• Relevant documentation does not exist. Instead, you are told that delivering more features faster takes priority, and that "good code documents itself!"
• Docs are never useful enough to get you onboarded to a new codebase. If you ask about a task, you're told to search for an obscure, unintuitively-named document in the company Google Drive.
• Jobs are sold to you as "High Documentation" workplaces, but that really means they have a Confluence graveyard of outdated design docs, and absolutely nothing on how to actually set up and use internal devtools.
• "Documenting new auth endpoints is not currently a priority. Use the V1 docs we have lying around somewhere, and ask in Slack to fill in the blanks."

Death by a thousand paper cuts.

If this keeps happening to you across multiple projects, would you trust documentation? Would you go the extra mile to create and maintain good docs, knowing it's going to be near-impossible to find, outdated in mere months, and precious project-specific knowledge lost with employee turnover?

"Documentation" Isn't a Monolith

You can build as much tooling as you want on top of the current process, but it won't help. Here's the 'secret' most people looking for a solution never seem to get.

Modern software development involves deep, specialized skills that grow with domain experience. This experience gained isn't just proficiency in languages and dev tools, but also how to approach and solve unique, domain-specific problems with constraints that might not be immediately obvious.

This is why documentation can never be a singular, "Superman" entity that - when created - meets every single knowledge requirement.

Speaking from experience, here's how devs gradually build that knowledge. Documentation is not one, but four needs - each prevalent at a certain stage of this process.

This is why the way organizations currently do documentation won't get you there. Forcing the issue inevitably leads to documentation that is confused. It's either too broad or too narrow to be useful, naturally difficult to write, maintain, and canonize - thus easily outdated and fragmented, existing only as ephemeral, tribal knowledge.

Instead, you need to create more focused, structured documentation that explicitly references parts of your codebase - and is created, stored, and updated alongside it.

Which brings us to Swimm.

Swimm - Winning Back Trust in Documentation

Swimm specializes in making code-coupled docs easier to write, maintain, and find across teams and repositories, with an editor that can do rich-text as well as Markdown enhanced with code snippets. They also have Slack and IDE integrations (Jetbrains and VS Code) that let you get local previews of your docs, even when working offline.

Before we get into Swimm, though, let's get my personal biases out of the way first:

1. I'm not interested in a solution that's just another Notion or Confluence, bundled with just another Bitbucket and Jira. I'm burnt out on tooling built on top of existing ways orgs do documentation.
2. I really do like the Docs-as-code approach in general, but...I can just use a standard self-hosted, battle-tested ReadTheDocs solution for that. It has to offer something more.
3. Nothing turns me off faster than being vendor-locked.
4. If I have to upload code directly to a SaaS' servers, I may need to clear it with Legal first - and that'll slow my documentation efforts to a crawl, leaving me wondering if it was even worth it. So that's a non-starter.

Given those requirements, how does Swimm fare? Here are my takeaways.

How to set up Swimm

If you want to use Swimm, you sign up with an account, and hook up your GitHub repo.

The process is simple, but it is currently GitHub only. I believe support for additional platforms like GitLab and BitBucket is on the way, though.

Also, getting the Swimm Github App is technically optional, but I strongly recommend you consider it as essential as, say, keeping strict mode on for TypeScript development. You'll see why soon enough.

Swimm's privacy and security policy is really good. They're SOC 2 and ISO27001 compliant, and neither your GitHub Auth Token nor your code is ever sent to or stored on Swimm servers. The app uses GitHub OAuth, and only needs permissions to read your repo, analyze changes periodically, and write the documentation you create using it, in a separate .swm directory.

💡 If you're part of an organization, though, Swimm does need to know which Organizations own the repos you'll be working on, so it can grant individual repo permissions within it.

Writing structured, focused documentation is easy when it's code-coupled

The thing that impresses me right off the bat is how you create documentation in Swimm. Linking your GitHub repo isn't just an auth solution, it also means you can now directly refer to files in your repo.

...or any code, anywhere in it. Variables, Functions, and yes, even entire code snippets.

This is already a step in the right direction, because right away, what I'm writing here isn't 'docs' as we know it anymore - not just another thing that's going to get thrown into a disorganized Notion or Confluence and forgotten, but documentation that has 1:1 mapping to the codebase and will be actually useful to developers.

More importantly, since it all starts with code, this is documentation that is incredibly easy to write and illustrate using Markdown, diagrams, and images.

All good, but hold on a second. Let's think back to how documentation isn't one need, but four. If I wanted to implement the approach that I talked about in that section - distinct, focused, structured documentation - could I do that?

I'm glad to say the answer is yes. The ability to write Markdown enhanced with images, Mermaid diagrams/flowcharts, screenshots, and direct references to code snippets would already make it possible to do so yourself, and be confident that it'll all be up to date through a series of various checks.

But Swimm also provides templates for this purpose. This makes it trivially easy to create and maintain:

• Data Flows and Component-level overviews,
• Quickstart guides, eg. setting up dev environments,
• High-level engineering overviews to help new team members get acclimatized,
• Design docs,
• and Technical Reference (think API docs) that describe details, field-by-field.

Even the most literature-averse, boots-on-the-ground developer would have no trouble doing any of this. All they'd have to do is what they already do best - talk about the code.

It's not going to be perfect, not on a first pass, but it'll be infinitely more useful to anyone reading it than five lonely, outdated documents, scattered in the company cloud would.

All of this, once committed, is going to get saved in a .swm folder in the same repo, meaning it lives alongside the code as plain markdown files (the only addition being frontmatter for Swimm internals). Nothing is obscured, and there is no vendor lock. All your .md docs are obtainable with a fresh git pull and editable outside Swimm if you wanted to.

A really good quality-of-life feature Swimm provides here is the option between either pushing to main, or creating a new branch with a PR. If you trust your team and don't want minor documentation fixes (say, a typo correction) to be held up in Git peer review alongside code on main, just make a new branch for the docs. You can then merge that without any conflict, delete the branch, and repeat as needed.

The documentation is always where I need it most - the IDE

So yeah. Swimm makes it easy and intuitive to write good docs, but that would be a band-aid fix at best if I still have to rummage around in a thousand different places to track it down.

What if I could have the documentation right beside me when I work with code? Without having to Alt-tab out to Confluence, Wikis, GitHub, and Slack?

Turns out, Swimm had exactly the same idea, and their IDE extension lets you do just that. So go ahead and install it depending on if you use Jetbrains (here) or VS Code (recommended, here), and then the next time you open your IDE, sign in using your Swimm account, and scroll to the file/section of code which has docs already written and available to see - you'll see this Swimm icon, with previews of the docs associated with that block.

Go ahead and click them, and you'll be able to open docs associated with those blocks of code in the Swimm webapp, or - even better - inside your IDE itself.

No exhausting Alt-Tab sessions, context switching, or going on scavenger hunts for docs based on table scraps left in the company Slack.

Before moving on, though, a minor gripe. I don't like that you can't create docs directly from the IDE. You'd have to use the Swimm webapp in the browser for that, meaning at minimum, you'd still have to Alt-Tab between your IDE and your browser while creating documentation. Given that all of Swimm's documentation is in markdown, anyway, this seems like a feature that's too intuitive to not be there.

The Swimm IDE Marketplace assures me that support for it is on the way, though. Sweet!

Swimm's 'Auto-sync' feature is Docs-as-Code on steroids

Writing good docs is only part of the process. How do you make sure it stays up to date?

To demonstrate, I'll go back to my IDE now and change some of this code (changing the timestamp property to a more human-readable version), and commit it.

If I go back to the docs again, as a reader, Swimm immediately notices it and tells me this part of the code isn't in sync anymore. Swimm has done its best to use its patented "Auto-sync" technology to include the new code, but it still needs manual review.

As a reader, though, you have all the information you need right in the docs - including when it was last updated, and by whom. No need for guesswork.

Reader and Editor views.

As an editor, it shows me the same information, but with a diff view to make it as easy as possible for me to review the changes. Very nice! All I'd have to do here is review this Auto-sync operation, and commit again to fix it.

Also, if we're talking about breaking changes, like entire files being gone in a refactor (very common if, say, you've rearchitected your app to migrate to a more type safe TypeScript + tRPC + Zod version), Swimm won't attempt to Auto-sync at all but will let you know right away that the entire document is outdated, and ask you to update the docs to match the new architecture.

Finally, what happens to your build pipeline if your docs aren't up to date? Here's a scenario where a teammate has pushed a significant update to a CustomButton component, but since it doesn't have updated Swimm docs to go along with it, merging it into the main branch would mean leaving a documentation black hole.

Fortunately, the Github Swimm App realizes this, integrates into your CI/CD workflow, and fails your builds until docs are updated. This makes sure you never push an update to your code until it has its associated documentation updated. This is the final line of defense Swimm affords you against stale docs that do not reflect the current state of the code.

Overall, Swimm has a much easier, feature-packed workflow than typical docs-as-code solutions.

Playlists make knowledge-sharing intuitive and joyful

Playlists are an incredibly fun concept that has me very excited for potential use cases.

You create an ordered view (think Spotify playlists) of markdown, videos, external links, and even existing Swimm docs if need be, to communicate an idea, or concept. It's like an experienced teammate or mentor walking you through the code, step by step.

Swimm Playlists can be used for anything that needs a series of steps - but the most obvious use case for them is, of course, employee onboarding.

As an example, let's say you use TailwindCSS as your styling solution. If your new hire is familiar with something else - Material UI, just Sass, or no design system at all - this is where you'd make a playlist to help them grok Tailwind's utility-first concepts before starting.

Swimm keeps track of progress in a Playlist, so you don't have to remember where you've left off.

They are also key for employee offboarding. Playlists can be used to store ephemeral knowledge - optimization hacks, tips and tricks, quirks of legacy code, shortcuts, etc. - to make sure anything that you haven't covered in canonical documentation isn't lost when experienced employees move on.

These Playlists are markdown files too and live in your repo. And again, just like regular Swimm docs, they are kept Auto-synced and up to date.

The Era of Continuous Documentation

With that, we've reached the end of this review. Hopefully, you realize that even though documentation is widely seen as the tedious, manual labor of the software development world - it doesn't have to be.

It's a matter of working smarter - not harder. A matter of new documentation paradigms - not new technologies built on top of what has already let developers down.

Swimm isn't perfect - but it's the closest that anyone has come to understanding how the process of knowledge accumulation is different for modern software development, and how its needs are different.

It's no surprise, then, that Swimm's paradigm of code-coupled, Auto-synced Continuous Documentation that treats documentation as first-class citizens alongside the development process itself, is the help developers have deserved and waited for, since forever.

You can try Swimm out for yourself here.