Create a Swimm Doc

This doc will walk you through the process of creating a Swimm doc on your own repo.

Not ready to start with your own repo? Try out our demo repo.

Need help connecting Swimm's repo? Check our Git provider guides to connect your repositories to Swimm.

info

If you create your Swimm doc from your workspace home, be sure to select your intended repository. The doc will be created on the default branch. If you want to create a doc on a specific branch within the repo, navigate to the repository and select the branch from the dropdown in the breadcrumbs up top. Remember that docs are saved as Markdown files within the repo just like other code files. This branch is where the doc will be saved.

Step 1: Pick a way to get started

Blank Doc - Just as it sounds, this is a blank doc page. Choose this option if you are clear about what you want to write.

Playlist - An ordered sequence of documents and other resources.

Pull Request - We pull all the code parts from any PR as a scaffold for creating your doc.

Step 2: Choose a title

Start by giving your document a title. Our recommendation is to be as descriptive as possible - How to post analytics is a better title than Analytics, as the former tells the reader what they will learn from reading the doc.

Step 3: Use Swimm’s code-coupled editor to edit and add content

Swimm’s slash editor commands are a great way to quickly create and edit content in your documents.

To use these commands, type / at any line and you will see the commands menu.

Swimm commands menu:

To pick a command, start typing its name followed by “Enter” or just click on it.

Important Swimm commands:

• Path- Add a path of a directory or a file in your document. Swimm will track it in case it is renamed, moved, or deleted.
• Doc - Add a link to an existing Swimm doc. Swimm will track it in case it is getting out of date and notify.
• Playlist - Add a link to an existing Playlist. Swimm will track it and notify you if it’s out of date.
• Code Snippet - Add live code to your document with code snippets.
• Diagram- Add a code-coupled diagram.

Step 4: Add Code Snippets

Start from your code

It is so much easier to create an effective document when you start from the code. Select your code snippets first, and write text later.

Type /Code and select to add a code snippet. Our Snippet Studio will show up.

Snippet Studio provides you with an easy way to locate a file and select a certain section from it. Once you have selected the code section, click “Add & Exit” (or press “Enter”).

This will add the code snippet to your document.

Above the snippet, you will see an area to describe and write about the snippet. This part does not need to be long. Best to just describe what the snippet does.

Snippets from multiple repositories

Since Swimm has access to all repos authorized, we take advantage of being able to include code-coupled elements from multiple repositories.

Step 5: Add Smart Tokens

Smart Tokens help you keep your documentation up to date by allowing you to reference parts of your code even outside of snippets in a way that automatically updates when the code changes.

The most common use for Smart Tokens is referencing variable, method, or function names within the document.

Step 6: Save and commit

• Click on the “Commit 1 Change” button in the top right corner.
• Create a new branch to start a PR or push to an existing branch.

All docs will be saved under the .swm folder once the docs are committed to the repo.

---

This document is automatically kept up to date using Swimm.