Skip to main content

Editing Swimm Docs

Further Reading

Have a look at our blog about Swimm's Editor to learn how we designed and built our fluid documentation editor.

Swimm Editor Features

Swimm's Editor, in many ways, is similar to other editors you may be familiar with. But we designed Swimm's Fluid Editor to help facilitate writing documentation. Therefore it has extra features to help you create Walkthrough Documentation - code-coupled documents explicitly referencing parts of the codebase.

Components are just a / away

Swimm Editor Features are easily accessible by typing the / key.
This brings up a menu where you can select what you want to include.
To get started, we recommend grabbing a bunch of code snippets.
This will provide a useful starting place to write the narrative to walk someone through the code.

Slash commands

Commands for Swimm's Fluid Editor include:

  • Path: A path to a file or a folder
  • Snippet: Code snippets from your repository
  • Image: Upload an image
  • Doc: A link to a Swimm document
  • Playlist: A link to a Swimm Playlist
  • Table: Create a table
  • Giphy

Bring helpful context through the Snippet Studio

It's very easy to combine code from multiple files in the same document.
This is useful for teaching someone how different parts of the code come together when it runs.

A useful example is client code and stylesheets, referencing how models work within the controllers that call them, or any other time where you need to teach how things fit into the larger picture and how individual functions and methods work.

Snippet Studio

Make documentation people will want to read

When creating documentation, including flow charts and diagrams is helpful for others to understand what you are trying to describe. Images, videos, and GIFs also make documentation easier to consume, and therefore more valuable to others on your team. In our experience at Swimm, reviewing great documentation helps encourage others to write more documentation for their team.

Flow Chart Image