How much time do I need to invest in creating content on Swimm before I see value?
Very little. From our experience, with a few hours of work, you can help your devs save days to weeks in ramp-up time. You can also easily incorporate content creation into your workflow, by creating documentation from pull requests and commits that encapsulate parts of the code you need to document.
So, what’s the difference between Swimm content and regular documentation?
Swimm allows you to build documentation that includes “live” snippets from your code. This becomes easily manageable thanks to our autosync algorithm that helps users keep these snippets up-to-date. Coupling documentation with the code also means it’s more focused, easy to find while you’re working and gives you a view of your “documentation coverage”.
So, with Swimm you get far better internal documentation with far less time investment.
Comments on the code are also coupled with it. Is Swimm like comments?
Comments help understand the specific lines of code they are associated with. Understanding code, and especially complex code scenarios, usually requires following a flow of code from different files, and sometimes different repos. Comments do not help with that. Also, if you forget to update a comment, you don’t get a notification or warning.
Swimm doesn’t replace comments in code – it augments them. It puts the narrative right where you need to find it, in your IDE. You’ll see that it’s there for your team, if they need it, when they need it.
Are there alternatives to Swimm? Who are your competitors?
To the best of our knowledge, there is no tool out there that creates code-coupled tutorials that remain up to date when the code changes.
The main alternative to using Swimm is not having high-res internal documentation. You can compensate for that by investing more veteran developer time on “hand-holding” new hires and devs switching between projects. Naturally, this becomes increasingly difficult as the team grows, or if you’re working remotely.
How can Swimm be used to help with setting up a new hire’s environment?
Our clients use Swimm in two ways to help new hires with their initial setup:
- Create an organized set of steps the onboardees should take and validate themselves. These steps can also be linked to code snippets (e.g., MAKEFILEs or devops scripts).
- Create hands-on Swimm docs that explain parts of the deployment / build / debugging process.
We already have different kinds of documentation, recorded lectures etc. Do we need to import them to Swimm?
Many of our clients had documentation on several platforms when they installed Swimm. The shortest and easiest way to incorporate them into Swimm is to link to them from within a playlist on Swimm. This is a useful way to curate the important parts into subjects. It is also possible to link from other platforms to Swimm Units or Playlists.
If there’s a particular integration you would like, please write to us about it at info@swimm.io .
What about security? What do you store online and what stays on our servers?
All content you create using Swimm is stored as .swm files on your repository. Only users with access to your repository can access this content. Swimm does not have outside access to your code or to these files.
We do store some metadata such as workspace names, as well as user names and usage information (e.g., user x started unit y at time t). See our privacy policy for more information.
We use multiple repos. Does Swimm support that?
Yes. You can set up a Workspace on Swimm with multiple repositories, and create playlists that include steps from multiple repositories.
What languages does Swimm support? What about VCS’s?
We are language agnostic and support all languages. Swimm’s continuous integration tools work on all Git hosting platforms and Swimm has a GitHub app that runs documentation checks and provides helpful comments when they fail.
Swimm relies on Git, and currently does not support other version control systems (VCS’s) other than Git (like Mercurial, Perforce, etc.).
How is data, created with Swimm, synced between team members?
The same way you sync your code – Via your code repository and Git. Swimm units are stored as .swm.md files on your repo. When you create new content or change existing content, you need to push the .swm.md files to wherever your other teammates can see them.
If you’d like to see Swimm up close, sign up for a Swimm demo.
