DEV Community

Omer Rosenbaum
Omer Rosenbaum

Posted on

Why Markdown?

Here's the rationale behind our decision to base our docs' format on Markdown.

Why Markdown?

  • COMPATIBILITY! For example, if you're using Notion and Confluence to document your code, you can easily import to Swimm
  • GitHub and the IDEs know how to parse & render Markdowns
  • Markdown has become a standard and ultimately makes documentation easier

Why we moved?

  • We used to store content as .swm files in JSON format. So yes, it was easier for computers to read, but it wasn't readable as text and it didn't render in editors
  • .swm was not user friendly
  • we struggled to review changes
  • JSON's curly bracket format made editing harder than it needed to be

First things first, here is what sw.md looks like in:
Github
sw.md-github

VSCode
sw.md-vscode

Learn more about docs as code here.

Top comments (0)