Today I’m bringing you in from 30,000 feet to understand Swimm’s sw.md format and the rationale behind Swimm’s decision to base our format on Markdown.
But before I jump in, since this question comes up all the time: sw.md is pronounced ‘swahm-dee’ or ‘swimm-dee’ in the same way you’d pronounce Markdown (.md) as “emm-dee”.
What is sw.md?
Sw.md is the new file format Swimm uses to represent our documentation. Sw.md is a Markdown file: it’s a file that’s meant to be read on its own as it is – a textual file with some styling input.
When you create documentation with Swimm’s platform, it is automatically saved in sw.md Markdown format. So, for example, when you have headers, code snippets etc, Swimm enhances that Markdown format by adding in sections needed to operate and connect the data.
Sw.md in GitHub
Sw.md in VSCode
Advantages to sw.md Markdown
Swimm’s sw.md Markdown has:
- a metadata section we use to track things internally, like the ID of the file
- code snippet sections which present the referenced code in a way that is both legible by humans and computers.
- a way to represent the Smart Tokens feature. If you look at sw.md as it’s rendered, the Smart Tokens has a superscript marker and once you click it, you can see the code that referenced the Smart Token in the code; Swimm keeps track of it, so we can make sure it’s up to date.
Other benefits to sw.md Markdown: it’s easily shareable; you can read and review it directly from Github or the IDE; you can edit your documentation there (as long as you don’t change the Swimm specific sections) and even use it in other services that support a Markdown format.
Why Swimm moved from .swm to sw.md Markdown
During the early stages of Swimm’s product, all content was stored as .swm files in your repository. Swm files were in JSON format, and though it was easier for computers to read, it was neither readable as text nor rendered in editors, it was not user-friendly, changes were hard to review, and editing was harder due to JSON’s fragile curly bracket format.
Swm Format
In short, swm was not working out. Swimm did not want to begin dealing with yet another proprietary format. We felt it was much better to focus on using known readable file standards that require very little to no explanation at all.
In August of 2021, Swimm switched to sw.md Markdown and there’s no going back. It was an easy move, plus there was precedent for extending Markdown with new functionality by adding new markup.
sw.md Markdown compatibility
Using Markdown allows us to be mostly compatible with other enterprise products without much work on the part of our customers. If there are other services or processes that use the Markdown format, they can use the sw.md files and process them. So software like Notion and Confluence use the Markdown format and it makes it easier to import to Swimm.
Both Github and the IDEs also know how to parse and render Markdowns so that makes it easier to consume that content there instead of going to Swimm – and in some cases even edit there.
Bottom line
Swimm uses Markdown for lots of reasons including the fact that Github and IDEs render Markdown files nicely, it’s easier to read, and even supports editing. Markdown is an easier way to do documentation and has become a standard in the industry.
With sw.md, you get the best of both worlds. You get a text that is readable in your code base, and you have control over it. And all of this while enjoying Swimm features keeping your documentation up to date and utilizing an editor to create the files.
Dev team workflows are definitely changing, and there are lots of reasons that this is the case. If you are interested in integrating Continuous Documentation into your team’s development workflow so that code-coupled documents in your CI and IDE are always up to date, sign up for a 1:1 Swimm demo and see firsthand how Swimm can be a game-changer for your R&D team.
