The past few years have provided additional flexibility to employee teams around the world in terms of working in remote offices. We are working in more remote locations and on more remote engineering teams than ever before. And thankfully, we have affordable software enabling our productivity.
The obvious trade-off is that everyone is in a different location and possibly various time zones, and we can’t just tap someone’s shoulder to ask for help. Even if our coworkers are in the same city, we’re not always in the same space.
We do have Slack and Zoom to talk about work and everyday life, but software developers need more than chat and file sharing. Our work requires long periods of focused concentration on complex technical tasks and an ability to easily context switch from one project to another. Moreover, our job constantly consists of understanding code other team members have written.
There aren’t many tools built for this type of work, but Swimm was designed with developers—and dev teams’ day-to-day work needs—in mind.
Why Swimm is good for remote engineering teams
One of the biggest challenges of being a developer is the need for support when onboarding a new team, project, or codebase. The complexity of software means there’s a mess of figuring out what to learn.
Devs are left asking: “Where is the actual documentation I need? Where can I find information about this project?” On a daily basis, code evolves, and engineering teams need to be able to understand the recent changes to the codebase. When you’re remote, you can’t easily ask people what’s the newest and most accurate information.
Swimm solves this problem with code-coupled documentation. We have sophisticated systems that ensure docs are accurate and updated, and this gives teams a sense of trust in the docs and provides a meaningful source of truth for engineering teams needing help, especially as the code quickly evolves. Plus, the documentation is easy to find—right next to the code in your IDE. So you no longer have to look for the documentation.
Swimm can provide a guided onboarding experience as if someone was at the desk next to you telling you what to read after you’ve finished the first document. We allow users to create documentation Playlists that tailor the onboarding experience and help remote engineering teams feel more included.
A quick example: we create a personalized Playlist for every new employee at Swimm. Even though it’s done asynchronously, something as simple as “Jesse’s first-day Playlist” can create a welcoming culture. We may not have an office where someone can smile and shake your hand on the first day, but our Playlists are almost as good as first-day donuts at your desk (almost!).
Swimm’s features make remote work easier for developers
We take our work seriously and depend on Swimm ourselves. As developers, we know when a feature is handy and when it’s not. Remote teams like ours can’t afford to waste time, and we’ve created innovative new features that no other platform can match, like IDE-integrated documentation with Swimm’s IDE plugins and easily creating documentation with code snippets using Swimm’s code-coupled editor.
Collaboration, communication, and knowledge sharing are key to our tech culture, and Swimm’s unique capabilities are built on the idea that accurate documentation builds trust and enables others to grow.
Share knowledge with documentation
Engineering teams often have questions when working in specific areas of code. They’ll want to ask, “Why does the code look this way?” or “Who decided to use parameters like this?” When teams are in the same room, it’s easy to learn who wrote what, etc.
The implementation of knowledge sharing for remote engineering teams is definitely more of a challenge. This is where Swimm’s platform steps in.
Swimm first shows developers in their IDEs where code is included in a document and can connect another developer with the person who wrote the original code. In this way, Swimm’s documentation platform effectively encourages collaboration on existing documentation. This may include developers adding a few sentences about a bug fix or adding a bit of context about a confusing non-standard process that requires a tad more clarification. Or this may include creating a new doc, and helping developers find it, so they know—first and foremost that documentation even exists.
Sync documentation with your code
Even trivial code changes can introduce breaking changes to documentation. Something as simple as changing a variable name can make a document immediately become outdated in a static documentation platform like Notion and Confluence.
Swimm, however, is dynamic and keeps track of every code change, commit, and pull request in a repository. When it detects a documentation-affecting change, it alerts the developer and (depending on configuration) updates docs before the code is committed or the pull request is merged. Even with insignificant deviations in your codebase, when developers stumble upon these deviations, we cannot help but lose trust in the documentation as a whole. After all, we assume that if there are some parts of the documentation that are out of date, there surely must be other parts too.
Our easy-to-use interface lets devs update docs quickly. And Swimm also updates docs automatically with Auto-sync, preserving and sharing knowledge—tied directly to the code—to explain what a dev was doing before the context is forgotten.
Use Mermaid diagrams for high-level graphical knowledge
Swimm has native Mermaid functionality for diagrams allowing you to directly include code-generated, high-level designs and diagrams in docs, creating graphs of user journeys to visualize processes or data flows.
Here you can see Mermaid and Swimm in action.
Mermaid can replace the whiteboard from the physical world—and there’s no need to interpret someone’s messy handwriting! Mermaid diagrams in Swimm can even use Swimm tokens, so if functions or variables are renamed or altered, the Mermaid doc will get flagged and updated.
Bottom line
When remote workers feel lost, it’s harder to move forward productively. Swimm facilitates remote teams documenting technical details and surfacing issues to make sure everything about documentation is easier, smoother, and less frustrating.
Swimm is really changing the code documentation landscape from the ground up. Have a look for yourself and sign up for a free demo.
