Skip to main content

Swimm Trial Handbook

Intro​

This document is a guide for running a trial of Swimm, a tool for managing and creating documentation within your organization. The trial is designed to help you better understand the capabilities of Swimm and the value it can bring to your organization. The trial has several key goals, including validating that Swimm can accomplish everything you expect, mapping your organization's most important knowledge transfer needs, and creating a batch of valuable documents.

The trial is broken down into several stages, including trial preparation, a Docuthon event, further usage and assessment, and a trial summary. Additionally, this document includes information on the procurement process and an appendix with security resources and Swimm services for the Enterprise plan.

Trial Goals​

Swimm trial should allow you to:

  1. Better understand Swimm’s capabilities; and the value you can get from using Swimm.
  2. Validate that Swimm can accomplish everything you expect.
  3. Map the most important knowledge-transferring needs in your organization, and a plan to address them.
  4. Create a batch of valuable documents.

High-level Timeline​

  1. Trial preparation (before the trial starts)
  2. Docuthon (trial starts)
    1. During the two weeks, you will be able to add as many users and repositories as you wish, to fully assess Swimm.
    2. Further usage and assessment (two weeks)
  3. Trial summary
  4. Procurement process

Trial preparation​

  1. Trial setup - a short session where we define the use cases to focus on during the trial; and explain the trial's structure.
  2. Docuthon prep - deciding on focus points for the Docuthon, and assigning team members to various tasks.

What should we focus on?​

During the trial setup we focus on specific use cases that are important for your organization. We focus on use cases that will provide value in the short term, where knowledge will be transferred anyway, and using Swimm's platform and methodology would help transfer the knowledge in the most effective way.

An example of such use cases can be a major infrastructure change (e.g., breaking a monolith into microservices), where many engineers need to know and understand the new architecture. Another use case is parts of the code where only few engineers can now contribute, which creates an immediate bottleneck. Another common use case is a specific service that many teams use, and the team responsible for the service gets either swamped with questions or needs to account for misuses by other teams.

Docuthon​

A Docuthon is Swimm’s proven way to help teams get started with documentation practices or continue to adopt them.

Goals​

  1. Get to know Swimm terminology and its main features.
  2. Plan an initial list of docs and playlists.
  3. Get practical tips and best practices from the Swimm team.

Technical setup - before the Docuthon​

  1. Create a workspace at https://app.swimm.io.
  2. Connect your repository.
  3. Install our GitHub App.
  4. Invite the team members.

Method​

During a 2-hour Docuthon we identify the most important parts that require documentation. We provide an interactive demo and share practical tips about creating useful documents and using Swimm. Lastly, we actually write a few meaningful documents that are then there to last.

Resources​

Swimm’s GitHub app - documentation. Tips for a Successful Docuthon (a guide to run Docuthons yourself, with the Trial - the Swimm team will be there to guide the Docuthon).

Further usage & assessment​

During the two weeks following the Docuthon, your team will use Swimm and assess its capabilities. Use that time to create more documents, share them, and see what happens when the code changes as part of the development process.

Procurement process​

So, you’re ready to upgrade your account. That’s great! Here are resources and information that can help you get this approved in your company and complete the upgrade:

Information about our pricing - link.

Note: Discounts may be available, depending on the number of users.

Our terms of service - link.

Note - We do not negotiate these terms of service for the free or Team plans. If you are planning on upgrading to the Enterprise plan with more than 50 users, contact us regarding a tailored contract.

Security approval - Please see Appendix 1 for security-related resources.

Swimm’s customer services - Please see Appendix 2 for a brief description of our services.

Evaluating Swimm’s ROI - Please see Appendix X 3 to see how you can estimate the expected return on your investment in Swimm.

Contact Information​

For any questions, suggestions or requests, we are happily available via:

Appendices​

Appendix 1 - Security resources​

Privacy & Security

Swimm's Security​

info

We've prepared some frequently asked questions regarding Swimm's security profile, as well as information about Swimm's SOC 2 compliance.

Swimm's Privacy Policy​

You can read the entire Privacy Policy here.

Code Access & Storage​

TL;DR
  • Swimm does not modify any of your code
  • None of your actual code or content is stored on Swimm's servers
  • Your Git Provider token is not stored at any time on Swimm's servers
  • Swimm only changes a custom folder created for documentation ("/.swm")

Understanding Local Mode​

For our Enterprise clients, a "Local Mode" is possible. In "Local Mode", no code ever leaves your network, not even for processing.

ModeSwimm might modify code?Code is stored on Swimm?Access token is stored on Swimm?Documents are stored on Swimm?Parts of the code may be processed by Swimm's servers?
Default ModeNeverNeverNeverNever (unless enabled by admin)Yes
Local ModeNeverNeverNeverNever (unless enabled by admin)Never

Questions and Answers​

Who can see my code?​

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.

By default - Swimm processes parts of your code in order to make recommendations and suggestions for documentation that should be updated. In "Local Mode", all processing is done within your own network.

Does Swimm store the Git provider token that I provide?​

No. The token is not stored at any time on Swimm's servers. The token is stored on the client-side browser (local storage) in a manner that is only accessible in the Swimm app.

By default, Swimm will use your tokens to create doc recommendations in our effort to help you push forward creating docs for your team. The token can be sent to Swimm’s cloud functions for this purpose, and the transaction is encrypted. Note, the token is not stored on Swimm’s database or in any other storage data, and is only used for the duration of the action. In "Local Mode", all processing is done within your own network.

Will any of our code or content be stored on Swimm's servers?​

No. None of your actual code is stored on Swimm's server. By default, none of your content is stored on Swimm's servers either. Swimm only stores meta-data such as document titles, timestamps, usage statistics etc.

However, an admin of your workspace may enable sharing docs with users without code access for specific documents. In this case, a copy of the shared documents will be stored on Swimm's servers. Documents that have not been explicitly shared will not be stored on Swimm's servers.

Will Swimm ever make any changes to my code?​

Absolutely not. Swimm will create a folder in your repo to store the documents you create upon first login to the app /.swm/. After that, when you create documents and store them, Swimm saves the relevant file in the folder created in your repo. Swimm will not make any modifications to your code besides these files and will not change any existing code files. Every operation to the code starts with an explicit intent from the user, and the change management is performed on your version control system.

Can Swimm affect code in production?
No. Swimm does not modify any code in your production environment.

Does Swimm encrypt my data?
All data transferred to and from Swimm’s server will be encrypted during transit. Any data or metadata stored on Swimm’s servers will be encrypted at rest.

Sharing documents with users without code access​

TL;DR
  • An admin may enable sharing specific documents with users without code access.
  • In this case, a copy of the shared documents will be stored on Swimm's servers.
  • Documents that have not been explicitly shared will not be stored on Swimm's servers.

An admin of your workspace may enable sharing docs with users without code access for specific documents. In this case, a copy of the shared documents will be stored on Swimm's servers. Documents that have not been explicitly shared will not be stored on Swimm's servers.

Swimm CI Integration​

TL;DR
  • Swimm uses read permissions to verify that docs are in sync
  • Swimm will never apply code or document changes to your repository without user consent

Can the Swimm CI app affect code in production?​

No. Swimm does not modify any code in your production environment.

Compliance​

We are pleased to share that Swimm is SOC 2 and ISO 27001 compliant.​

Compliance with the SOC 2 standard is voluntary, but it has become increasingly important as companies select their service providers. For security-conscious businesses, SOC 2 compliance is now viewed as a minimal requirement when considering a SaaS provider, and it’s often a requirement in vendor contracts. To request Swimm’s full SOC 2 Type II report as of January 2023, send us an email at info@swimm.io. To receive the full report, you will need to sign an NDA. We can send proof of SOC 2 and ISO 27001 certification without an NDA.

Information for specific Git Hosting Providers​

Git Hosting OAuth​

Why is Swimm asking me OAuth into GitHub, GitLab, Bitbucket and Azure?​

Swimm uses OAuth to connect with your remote repositories in order to fetch relevant documents and verify if code snippets are up-to-date. In addition, Swimm enables users to issue Pull Requests to update documentation.

Git Hosting providers' authoring policy don't solely allow write permissions per directory. As a result, Swimm needs organizational, read & write permissions to the designated documentation folder in your repository. We create a ./swm folder in order to store Swimm documents.

GitHub App​

See this entry.

Appendix 2 - Swimm services​

Building a Documentation Culture​

  • Advisory calls - the Swimm team has unique and substantial experience working with teams of different sizes on employing documentation practices. On a call with your team, we will identify the specific team’s needs and help design the best ways to gain the full value from Swimm.
  • Docuthons - a proven way to help teams get started with documentation practices or continue to adopt them. During a 2-hour Docuthon we identify the most important parts that require documentation, share practical tips about creating useful documents and using Swimm, and actually write a few meaningful documents that are then there to last.

Onboarding Additional Users and Teams​

In addition to onboarding the initial users and teams on our platform, we also offer support for onboarding additional users and teams as the use of Swimm evolves in the organization. Our team is here to ensure they have everything they need to effectively use the platform and collaborate on code documentation. We also provide training and guidance about documentation best practices and methodologies.

We offer:

  • Demos - Demonstration of the product for new teams
  • Onboarding - Group onboarding sessions for new users
  • Advisory calls and Docuthons as described above

Ongoing updates and support​

In addition to our onboarding and training support, we also offer technical support to assist you with any questions or issues that may arise.

We are constantly working on new features and updates, and we will keep you informed about any new developments that may be of interest to your team.

A Shared Slack channel is set up with each client. A community Slack channel is available for clients without a Slack account.

Great! I want to move forward. What now?​

Please contact us and let us know what you'd like to do:

  • Schedule a demo for a new team
  • Schedule a Docuthon to ramp up your documentation
  • Schedule an advisory call on how to promote documentation practices
  • Schedule an onboarding session for new users

Appendix 3 - Swimm ROI for leadership and finance​

{ TBD: Include (we need to finalize it) }

Appendix 4 - Methods to incorporate documentation in your team's workflow​

This is a short description of how teams effectively integrate documentation into their workflow.

The main goal is not to write documents for the sake of having documents, but when they are actually valuable.

The methods described can be used together or separately. We strongly recommend trying different methods and seeing what works best for your team.

As part of your sprints​

In the planning phase of your sprint, identify tasks that would require documentation. Add a sub-task that explicitly states that having documentation os part of the Definition of Done.

There are two approaches as to when it's best to create the documents for the relevant tasks:

  1. While working on the code, as part of the sprint, and the relevant PRs. The main advantage is that the knowledge is fresh in mind, yet the code may change a lot so you might update the document many times.
  2. Right after the sprint is over - that is, at the beginning of the subsequent sprint, start by documenting the relevant tasks from the previous sprint. At this stage the code is already in production and its version is less likely to drastically change, and the information is still relatively fresh.

Both approaches are effective, and different teams may prefer a different one and even switch between them.

Periodic Docuthons​

Docuthons are great for two main reasons:

  1. You stop and ask yourself, as a team, what documentation is currently lacking, not by considering individual tasks for the upcoming sprints, but actual cases where knowledge was missing.
  2. It is a way to allocate time for the entire team to invest in documentation.

Define code parts/patterns that require documentation​

Create a list of code areas that require documentation, such as important parts that not many people know, or interfaces between teams.

In addition, you may decide that every X should come with a document. For example, every time a new service is created, it should have a document describing its APIs and also how to set it up.

Bonus​

Use templates that are specific to your team. Especially if you decide to create a document for every X (such as every service), have a template for that.