To improve your documentation writing, having a tool that reduces friction from getting a thought in your head into a nicely formatted document is important. Markdown is exactly the tool for this job.
What is Markdown
Markdown is an open-sourced markup language that you can use to easily create an aesthetically pleasing document out of a simple text file. A markup language lets you write symbols and special characters within a body of text to signify certain formatting in the document. For example, each markup language has a specific syntax to mark text to be bold, italicized, or even to be marked as a header. It takes all of the fuss out of formatting a document like you might have to in Microsoft Word.
Markdown is the simplest of markup languages, and therefore the easiest to learn. If you are familiar with other markup languages such as HTML or LaTeX, then learning Markdown will be a breeze for you as its syntax is by far the simplest. This is because where HTML is meant for rendering webpages and LaTeX is meant for writing mathematical papers, Markdown is simply meant to write documents easily.
The Simplicity of Markdown
At its core, Markdown has nine or so basic rules that you can use to accomplish 95% of all document formatting you'll ever want. Here is a comprehensive Markdown guide for basic syntax that you can read through. This guide is very extensive and may take a while to get through, so I have also provided an example of these nine rules working together to format a document.
Markdown is so appealing is because it removes all of the difficulty of formatting a document and encodes them into a very easy-to-understand syntax. It also strips away unnecessary formatting choices from the writer. My biggest pet peeve when I create a new document on Google Drive is having to make sure the font and font size are to my liking or having to deal with setting my margins properly. Markdown is all about what matters the most - the text you are writing. Problems like these are not apparent in Markdown because it simply removes that option altogether.
Another benefit is Markdown is that its file format .md is a universal file format that can be edited in any text editor, and opened in any markdown viewer. A big issue with Microsoft Word is that its .docx file type limits where you can edit the file. If you don't have a specific program installed on your computer to edit a .docx, then you'll have to turn to an online editor like Google Docs or Microsoft Word online. With Markdown, you can edit the file in any text editor. It is truly portable, and the same file can be used in many different applications without any conversion.
The stripped-down formatting options combined with the portability of the .md file is what makes the format useful yet simple. When you want to sit down and write some technical documentation or some notes, you don't want to worry about how to format it or compatibility issues across different applications. You just want to write, and that is exactly what Markdown enables.
Extended Markdown Syntax
It is also worth noting that there is more to Markdown than what you learned in the basic syntax. Markdown also has an extended syntax that builds upon the existing Markdown syntax. Unlike the basic syntax, the extended syntax is not supported by all Markdown editors and viewers. Most tools will state which features they support, so be on the lookout for that if you intend to use any of the extended features.
For a developer, one of the most useful extended syntax features is the ability to insert a fenced code block easily into a document. This is yet another reason why Markdown is appealing for a developer looking to write documentation. You can move between writing plaintext explanations to inserting code examples without any fuss.
Where to use Markdown
Markdown can be used in a variety of different places. Markdown Guide has a pretty thorough list of tools that support Markdown, though I am sure there are plenty more applications out there that support Markdown that did not make this list.
Slack is the place I find myself using Markdown the most often. Slack is far from a comprehensive Markdown editor, but it does support inline code highlighting and fenced code blocks. These two features are very valuable when it comes to communicating with colleagues. It is infinitely easier to understand a message about a technical problem when the code in the message is formatted differently than the regular text.
Without Markdown:
With Markdown:
Another place you'll see Markdown being used is on GitHub. By default, GitHub will render the README.md file in a folder when you are viewing that folder in the repository. Therefore, to write effective documentation for a repository you host on GitHub, knowing Markdown is a must.
There are also a variety of tools out there that let you write Markdown and render them on the web. Dev.to itself has you write your blog posts in Markdown - I am currently writing this post itself in Markdown! Prepare for inception:
GitHub Pages is another great tool that lets you turn a directory of Markdown pages into a full-blown website. On my old team at work, I led an initiative to create a set of Github Pages as a centralized source of documentation for the entire organization. This was a very simple, yet effective way to put all of our documentation and resources in one place. Be on the lookout for a future blog post on the creation of that.
I use Markdown daily in a variety of places. It is one of those underrated skills to know that people don't often mention but certainly improves both how we can write documentation writing and how we can communicate with peers.
If you've enjoyed this content, consider subscribing to my mailing list to be notified whenever I release new content.
Top comments (2)
Thank you for sharing. I use extended markdown (.mdx) in my blog which is made with Gatsby and React and I love it. It is so easy to work with, yet it's highly customizable. And it is easier to maintain content in markdown than html.
uselessdivs.com/
This Website uses markdown too