Part of what I’ve been doing more of lately is writing documentation for various projects. It’s interesting all of the various different formats that files can be stored in. The most common are probably word document files (Google & Microsoft), XLS (Microsoft Excel & Google Sheets) and PDF files.

For example, writing tech specs for clients usually involves writing them in Google Sheets or Microsoft Word files, but the formatting for these are usually terrible.

But lately I’ve started using Markdown for just about everything. Even though there are many flavors of markdown, I’m trying to stick to the Github Flavored Markdown.

I really like taking notes and writing documentation in Markdown because it can easily be created and written in any text editor or IDE. There’s no special software that requires vendor lock-in like Google or Microsoft.

Even the blog that I’m writing in right now supports writing posts in Markdown and rendering them with Jekyll.

If you’re a windows or Mac user there’s also plenty of apps like Inkdrop that make note-taking, etc super simple on these platforms.

So Why Do You Prefer Markdown?

I like Markdown because of the simplicity. For example, using Github Flavored Markdown, you can open Notepad and just start writing. You don’t have to worry about the graphic display of text, you can just focus on writing.

Markdown isn’t the only format out there, but it’s what’s most commonly accepted for version control tools like BitBucket, Gitlab and Github. I’m sure that there are others that can do things differently, but for right now, this is okay.

Markdown is also easy to use. Publishing documentation to Github pages is very straightforward because Github handles all of the heavy-lifting for you. If you need to save your Markdown files as PDF, there are also plenty of tools for that.

Using free tools like VSCode makes working with Markdown even easier to use. I personally prefer writing in plain-text but there are extensions for VSCode that let you preview what your Markdown will look like, if that’s your thing.

Since Markdown files are plain-text with markup in them, it’s great if you’re using version control software. The plain text files also make them more human and machine readable.

When I’m writing documentation, Markdown lets you easily enter codeblocks with just a little formmating.

Markdown doesn’t replace everything though. There are still specific needs for things like Spreadsheets and Word Documents, but you always want to be careful to choose the right tool for the job.