Swimm Helps New Dev Hires Stay Afloat with Continuous Documentation – InApps 2022

In their time working together at a boot camp focused on placing participants in STEM industries, four colleagues found a common challenge: onboarding developers to new companies. Upon joining these companies, the new hires were often faced with an opaque process, reliant on institutional knowledge that was often memorized, rather than written down. In response, the four (Gilad Navot, Oren Toledano, Tom Ahi Dror, and Omer Rosenbaum) joined together to create Swimm, a tool that helps teams to build tutorial units and documentation based on a company’s codebase and then assists with keeping that content up to date over time, which launches from beta this week.

“It takes a lot of time and effort to be ramped up. The main way companies used to onboard people was to throw them into the water, and then they either sink or swim. Our first focus started with that, with allowing engineers to be fully ramped up and onboarded quickly. With time we focused the problem into onboarding, not to a company, but to a code base,” said Omer Rosenbaum, Swimm co-founder and Chief Technology Officer.

The sink-or-swim saying, noted Rosenbaum, is how they arrived at the company’s name, as its goal is to help new developers stay afloat, rather than sink from a lack of guidance. In addition to creating individual units of documentation and tutorials, Swimm also allows users to create playlists, stringing together individual units to help create an onboarding curriculum.

Built with Javascript, Node.js, Vue.js, and Electron, Swimm provides a visual interface for creating documentation for codebases, with a command-line interface available for insertion in continuous integration and continuous delivery  (CI/CD) pipelines. The application is available as a desktop app for OSX, Windows and Linux. With Swimm, documentation can become a part of the software lifecycle, where changes to code can be compared during every build, alerting developers to when changes have become significant enough to warrant documentation changes.

“We allow the users to create tutorials from the code by selecting snippets of code and then attaching comments to them. When the code evolves, we analyze every git commit that happens since the unit was created,” explained Rosenbaum. “We look at how meaningful the difference is between the code — what it was like when the unit was created and what it is today — and if the change is not so meaningful, then we update it. If the change is really drastic, we notify the users that this documentation is now outdated, and that they need to update it.”

Rosenbaum said that these changes are analyzed using a recently patented technology that they developed by creating comments for open source projects and then taking the project through the process of changing over time, as available in its git repository. They then surveyed whether or not users would want documentation to be automatically synced or if the differences were too much. From there, they developed heuristics that could look at code bases over time to determine when changes required documentation updates. Rosenbaum emphasized that Swimm does not use static analysis, as they want to remain language agnostic. Instead, Swimm looks at code as a text string, meaning it can also work with JSON files, markdown, and any other non-binary text files that are stored in a git repository.

Beyond analyzing the significance of code changes, Swimm also handles a variety of more easily tracked changes, such as deleted code, changed class, function, and method names, as well as things like file and directory names, so that when changes occur in one location, they can be easily changed in others, if needed. In a pending update soon after launch, Rosenbaum said that users will also be able to use specific markdown to mark certain content, such as filepaths or functions, that should be auto-synced throughout the documentation when changed.

All of this, explained Rosenbaum, is part of Swimm’s approach toward continuous documentation, wherein it tightly couples tutorial-style documentation to a project’s codebase.

“Most engineers don’t like writing documentation because it’s hard, and it takes a lot of time, and even if you put in the time and the effort to create a really good set of tutorials and documentation, it turns out to be outdated very quickly,” said Rosenbaum. “What we mean by continuous documentation is, every time you push code, you run on your CI something that validates that all the documentation is still up to date. If something is outdated, deal with it now when everything is fresh and makes sense, continuously, by small steps.”

For now, Swimm operates both its user interface and its documentation through the browser itself, but Rosenbaum said that they plan on enabling documentation consumption for open source projects in a release as soon as next month.

InApps is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Swimm.