FAQs
We've assembled a list of the most frequently asked questions from our private
beta period. Be sure to
also check out Swimm's getting started guide.
🪪 Signing up & permission scope
Additional information about Swimm's security profile can be found here.
A Swimm Admin is a workspace member who has full access to workspace settings, integrations and account management. A Swimm Admin doesn't have to be an organization owner (like GitHub organization owner), nor a Slack Admin to integrate with Swimm.
Please reach out to on our Community Slack Channel if you have any questions about the Admin status.
Swimm does not store your documents or parts of your code. However, for GitHub users - GitHub authoring policy doesn't allow write permissions per directory, so Swimm needs organizational, read & write permissions to the designated documentation folder in your repository (a "./swm" folder we create in order to store the documents).
More about the 3 types of permissions:
- Organizational permission: You'll need to specify which organization owns the repos you'll be working on. This will allow you to grant Swimm individual repo permissions within that organization.
- Read permission: Swimm will need to be able to read your repository and access to the entire commit history in order to be able to understand and account for code changes. Note that your code remains in your repo, and Swimm simply stores metadata about snippets, paths, and tokens so that it can remember what it's supposed to keep track of.
- Write permission: Swimm uses a special directory named .swm/ in your repo to store your documentation along with a unique identifier that correlates your documentation to your repository.
Use the account associated with the organization you're working for. In almost all cases, this is very likely to be your personal GitHub account, even if you received a workspace invitation to your work email address.
🔐 Security & privacy
Safety and security are a top priority at Swimm.
- None of your actual code or content is stored on Swimm's server. Swimm only stores meta-data such as document titles, timestamps, usage statistics etc.
- All data transferred to and from Swimm's server (Google Cloud Platform GCP) will be encrypted during transit. Any data or metadata stored on Swimm's servers will be encrypted at rest.
- Only you, and those who normally have access to it in your Git provider, can see your code. Swimm never makes a copy of your code.
To learn more, read our security page.
Is Swimm SOC 2 compliant?
Swimm is SOC 2 compliant.By default, images are uploaded to our secure Cloud storage. It is possible to enable a configuration to allow you to store images in your repo so that they are loaded with relative paths. For more information, please reach out to Swimm's support team in our Community Slack Channel or email us at info@swimm.io
💎 Why Swimm, benefits & ROI
Very little time!
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.
Swimm allows you to create code coupled documentation by adding live snippets from your code. Regular documentation systems are not built for software documentation because code changes rapidly and regular documentation solutions need to be manually maintained.
With Swimm, it becomes easily manageable thanks to Swimm's Auto-sync algorithm that helps users keep these snippets and your documentation always up to date.
Coupling documentation with the code also means it's more focused and easy to find while you're working - having your documentation available directly in your IDE where you need it. Code-coupled documentation also gives you new powerful ways to document your architecture, your classes, and your styling guides (and so on) in ways that weren't possible before.
With Swimm's platform you get far better internal documentation with much less time invested.
Comments help us understand the specific lines of code they are associated with. Understanding code, and especially complex code scenarios, usually require following a flow of code from different files and sometimes different repos. So comments do not help with that.
But also, if you forget to update a comment, you don't get a notification or warning to make an update. With Swimm's patented Auto-sync feature, we ensure that your documentation stays synced with the code as the code changes. So 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.
Swimm is a crossbreed between code comments and high-level documentation. With Swimm, you add code snippets to your docs so they are available right inside the doc whenever you select a code snippet. When you use one of Swimm’s IDE plugins, links to available documentation appear right within the code.
Because documentation is code-coupled, you find your documents in time, they describe flow and patterns using the actual code, documentation coverage is automatically detected and flagged, and there’s no more risk of code comments becoming outdated or accidentally deleted.
Clients using Swimm are reporting the following:
- Swimm is helping them spend up to 55% less time onboarding new employees.
- Swimm streamlines code documentation, linking the code and making it very convenient.
- Swimm has been critical for ensuring internal docs around the ecosystem stay up to date.
- Swimm helps developers become more open to the culture of documentation.
At the end of the day, Swimm is saving user teams hundreds of hours looking for knowledge and docs. Swimm understands well the friction and frustration around searching for something that you don't know if it even exists, coupled with the ongoing fear of knowledge loss and legacy code. These all are, unfortunately, very familiar problems for most organizations.
Swimm provides an effective and efficient way to reduce (and sometimes completely eliminate) these challenges. For more details here are some articles that address the impact of swimm over R&D teams:
Use cases for Swimm include:
- Complex Code: Create documentation for complex code and non-standard processes that is confusing and requires more information.
- Knowledge Sharing: Create documentation to eliminate legacy code and promote inclusive teams & knowledge sharing.
- Refactoring: Update parts of the documentation that require updating as a result of the refactoring, and let your team know about the changes.
- Research → Development: Document the infrastructure and research process used, and share the results with the development team. Having a research team share its results with the development team. Explain how to use the research outcomes during development.
- Internal API: Demonstrate flows of using the API internally.
Pseudo code snippets (codeblocks) are fundamentally different from Swimm snippets by their function and purpose.
- Codeblocks are used for demonstrating an example or usage of the code.
The example itself doesn't exist in the codebase and its purpose is to explain how things work. Codeblocks are not synced or automatically maintained by Swimm. - Swimm's code snippets are actual line-by-line code taken directly from the codebase. Snippets are synced and automatically maintained and updated by Swimm.
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.
Learning how to use Swimm is very straight forward, and easy to pick up.
Swimm functionality is primarily categorized as:
- Reading and creating documentation
- Creating Playlists
- Organizing documentation
- General documentation editor capabilities - as you would find in Notion or Confluence - such as "/heading 1", "/quote" or "/codeblock"
- Swimm special commands such as "/snippet" or "/doc"
- Swimm suggestions
- Swimm syncing capabilities
👩💻 Creating content
Smart Tokens are used to help you to write and edit docs that are interwoven with your codebase. By adding referenced code tokens (such as variables, functions, or class names) in your documentation, these live code references are tracked by Swimm to keep your documentation up to date. To add Smart Tokens in Swimm, type a Backtick ` anywhere in the editor. Read more about Smart Tokens here.
You can create a Playlist with documents that exist in one or more repositories. Simply navigate to another repo and select the docs you'd like to add. Note that Playlists can be embedded in other Playlists as well. Learn more about Swimm Playlists here.
Data that is created with Swimm is synced exactly the same way you sync your code - via your code repository and Git.
Remember that Swimm units are stored as Markdown files on your repo under the ./swm folder. When you create or edit content, you commit it to your repository which can be reviewed, approved, and merged to a branch. It is shared when your teammates pull the latest version of the branch.
Swimm also has Cloud docs which are similar to common documentation tools. Cloud Docs are not coupled to your repository and can be shared via a link to any Swimm user.
Many of our clients have documentation on several platforms when they install Swimm.
Your internal code-related documentation will get "superpowers" with Swimm compared to other documentation tools. If you are already using a documentation tool, we highly recommended using Swimm's Batch Import feature to bring over all of your docs and other relevant files.
If you decide to keep some of the documentation on other tools such as Notion or Confluence, the shortest and easiest way to incorporate them into Swimm is to link to them from within your docs or Playlists on Swimm. This is a useful way to curate the important parts of your documentation into subjects, and you can also link from other platforms to Swimm Documents or Playlists.
If there's a particular integration you would like to request, please let us know and contact us at info@swimm.io .
When creating code-coupled documentation, remember that you don't have to start from scratch. Swimm helps to the end with a bunch of options:
- You can use Swimm's Guide Doc Creation wizard to walk you through step-by-step to create a doc on any topic you'd like. We ask a series of questions and help you structure the document and understand which parts of the code you need to choose in order to explain it.
- Start creating documentation from a pull request. If there's a pull request that you just finished or one that is a good example of how to solve something specific we bring in all the important "Difs" as code snippets, and you can start documenting from there.
- Create documentation using Swimm Templates
- Import existing documentation, including Markdown files. You can also perform a batch import from an entire repository or a local folder that contains Markdown files.
You don't have to reserve developers' time for Swimm, and you can create documentation when needed. However, we have seen teams successfully reserve 1 hour in the beginning of every sprint to document the main outcomes of the previous sprint.
That said, to see immediate value from Swimm, it really takes a very short time - even just minutes. We recommend the following:
Step 1:
Find areas in the code that are common for new developers to start with. Some examples:- How to set up a new environment
- How to create a common component
- An overview of a system or a process
Step 2:
Make sure all team members install Swimm's IDE plugin. When your documentation appears naturally inside the IDE, it encourages your team to read it in context. What we know is that the key for investing in documentation is making sure people will find it easily when they need it the most.Swimm helps you create code-coupled documentation very quickly.
To get started consider the following method:
- Create a new document
- Add code snippets related to the topic
- In a sentence or two, describe what each snippet does
- Fill in the space between snippets by describing how they interconnect
With some practice, it can take just several minutes to create documentation to help your larger team understand aspects of the codebase that will benefit from the documentation. You can also use Swimm templatesfrom Swimm's template collection to help you get started writing a doc.
Swimm's Snippet Studio our web application allows you to add live code snippets directly to your docs.
- Start with Swimm's Snippet Studio.
Once you select a code snippet command, Swimm’s Snippet Studio will appear and help you locate a file and then select a certain section from it. Once you have selected the code section, click “Add & Exit” (or press “Enter”). - Find the file you are looking for
- Highlight a line or more of code
- Adjust the gray handles (the context) for additional or fewer lines
🧩 Integrations
See this page.
Swimm's GitHub app is a native integration created by Swimm leveraging GitHub's Check mechanism. This means that you don't have to run any manual scripts as part of your CI pipeline (unlike GitHub Actions) since the GitHub App takes care of all of this for you.
With Swimm's GitHub app, you can configure multiple configurations such as:
- Allowing Swimm to automatically update and commit minor, out-of-sync code snippet inconsistencies in your docs.
- Allowing Swimm to fail a check only when outdated/out-of-sync docs are caused by changes performed in the current PR by the developer, instead of changes that may have been performed in previous PRs by other developers.
- Allowing Swimm to alert you via a PR comment recommending you existing Swimm documentation that you should review when code changes.
- Receiving an email whenever a new doc was merged to the default branch.
If you're using GitHub, we strongly encourage you to install our GitHub app. This will provide the best possible experience for everyone involved from the originator of the PR all the way to the reviewer. For more information on Swimm's GitHub app, see here.
Swimm has an integration with VS Code enabling documentation icons over your code.
After installing Swimm's VS Code plugin, you will be asked to login to your Swimm account. If you don't have a Swimm account, you can register here.
After logging in, you will have a Swimm icon on your VS Code sidebar. Clicking it will show the Swimm panel with all the documentation already created.
When navigating to a code file that has Swimm documentation, a "wave icon" will appear in the code, right next to the lines that have been added to the Swimm doc. Make sure that you have added a code snippet to your Swimm Doc.
If you do have Swimm docs ("./swm/*.md) already and you don't see any documentation in the Swimm sidebar:
- Make sure you are working on the desired branch where the documentation exists
- Try logging out and logging in. In VScode the credentials appear on the user icon on the bottom left
- Make sure you have been added to the Swimm workspace where this doc lives
We currently do not support integrations with ticketing systems, however it is on our Swimm roadmap. Stay tuned.
Swimm IDE plugins for VS Code and the Jetbrains Suite are available in the Microsoft / Jetbrains marketplace. The current versions of the plugins are for read only documentation.
Swimm is currently working on a release to create documentation from the IDE. The release is planned in the coming months. If you want to know more exact roadmap details, please reach out to us on our Community Slack Channel.
⚙️ Workspaces & repositories
Yes, with Swimm, you can set up a workspace with multiple repositories.
You can also create Docs and Playlists with code snippets across multiple repositories.
From your main workspace page, select "Workspace Playlist". This will allow you to bring in docs and other playlists from any repositories in the workspace.
You can invite users, see pending invitations and manage your team by clicking the "invite" link at the top-right of the main workspace page.
Swimm has no limit to adding public repositories to your workspace.
In the Free plan, you can only add one private repository inside a workspace.
Paid plans (Standard and Pro) let you add unlimited private repositories.
🔧 General troubleshooting
Here are 3 of the best way to reach out to our Swimm Support team:
Reach out to us on our Community Slack Channel.
- You can also join the Community Slack Channel in the Help Center in the web app.
- Submit Swimm's "Give Feedback" form - also in the Help Center.
- Send us an email to info@swimm.io.
If you do not see the repository that you wish to add, most likely your organization doesn't have the correct Swimm permissions.
After you click "Connect Repository," click on the "Manage Scope" button to grant organizational access to Swimm, You may also ask your Admin at Swimm for additional assistance, or reach out to us on our Community Slack Channel.
Once you have Swimm extension installed in VS Code. Make sure that:
- You are logged in to your Swimm account (via the VS Code extension)
- You already have a least one Swimm document with at least one Code Snippet included.
If you want the other way around - open the file code referenced in the document.
- Have the document in front of you opened in the IDE (the
*.sw.mdfile) - above the snippet, you will see the name and path of the file that the snippet has been taken from
- Use VS Code native capabilities to quick jump to a file now that you have the path of the file in hand
You can invite a teammate via the Invite link located at the top right corner in the Swimm App. In the email input field, enter your teammate's email address. Alternatively, if you are looking to invite multiple teammates, separate their email addresses with a comma. When done, click the Send invite button.
Currently, it is not possible to ignore select files or folders for Auto-sync. However, it is on our Swimm roadmap.