Say yes to Markdown, no to MS Word

What on earth are you talking about? What’s wrong with our beloved and old companion Microsoft Word?

What is Markdown?

Markdown is a syntax language aiming for easy reading and writing of structured text. There are multiple implementations of the language (such as Github flavored Markdown) and each of these implementations have some own improvements and features that are not necessarily compatible with each other. Still each implementation bases on the same default syntax and when done right Markdown files are cross-compatible between different implementations.

Markdown is easy to learn and it only requires text editor to create your first document. The original Markdown syntax supports the following features:

• Paragraphs and line breaks
• Headers
• Blockquotes
• Lists
• Code blocks
• Horizontal rules
• Links
• Emphasis
• Images

By using just these features you can write out almost any document you could with Word. Markdown also supports inline HTML that can be used to create content that the syntax doesn’t support.

Why would you use it?

There are lots of things that speak for Markdown and why it’s superior over .docx or .doc files. Here to list few of them:

• Version control. If you have a Word document that you are editing together with some other people, it is almost impossible to merge the changes together on version control such as git or svn. With Markdown this is quite straight forward as it works like any other text file merge. And yes I am aware of Office product having collaboration systems but still I see them a bit overburden for simple documentation process.
• Edit with any platform. One of the best things is that you can edit Markdown files on any platform with the editor of your choice. As a hardcore Linux fan this is one of the heavy arguments of using Markdown. Of course there are LibreOffice and other tools to handle Word documents on Linux but sometimes they mess up the formatting or are missing some functionality.
• Not only Word. Markdown is not only for writing text documents as there are tools you can create also presentable slide sets (like PowerPoint) from Markdown files. More about tools for this can be found from the last chapter.
• Limited features. This actually is a double-barreled handgun. With Word you have tens or even hundreds of buttons to do different kinds of formatting. With Markdown it’s much easier as it only supports limited features and you can easily learn the syntax in less than an hour. Limited features also means, most of the time, more readable and structured output.
• File size. Not a big matter now-a-days but single text file can store many times more information than a word document.
• Exportability. Everyone knows that exporting Word documents to pdf, html and other formats is possible. But so is the case with Markdown. There are multiple open-source tools available for this job which I will cover in the last chapter.

For these reasons I would suggest you at least try it out. There are online editors available for Markdown such as Dillinger or StackEdit. These editors also show you the rendered output in real time and are the fastest way to get to know Markdown. For actual documentation I suggest that you use some local editor such as Vim — especially if you are working on business sensitive documents.

What about other markup languages?

There are MANY other markup languages for example Textile (used for example in JIRA). I don’t see any problem with any of those as long as they can actually do the same things as Markdown does and provide the same advantages. Just try them and find out which suits you the best.

Task for you

If you are new to Markdown and actually tried it out I would love to hear your opinions how it would fit for your daily work! In case you are already using Markdown or any other markup language for your daily work, please let me know of good tools and practices using it. Especially automating documentation process (file conversions, online documentation etc.) is really something I would love to hear more about.

Also please share this story if you find this interesting way of doing documentation.

Tools

Here is a list of tools that might help you on the way:

• http://markdownpad.com/ — Markdown editor for Windows
• https://chrome.google.com/webstore/detail/markdown-editor/ekdcaddpmiodcipjfmffhhefijpdckaf — Markdown editor for Google Chrome
• https://github.com/plasticboy/vim-markdown — Markdown editor plugin for Vim
• https://github.com/alanshaw/markdown-pdf — Markdown pdf converter
• https://github.com/gnab/remark — Markdown slideshow tool

About me

I am Heikki Hellgren, Software developer and technology enthusiast working at Elektrobit Automotive. My interests are in software construction, tools, automatic testing and all the new and cool stuff like AI and autonomous driving. You can follow me on Medium and Twitter. Also you can check out my website for more information.