Four Key Reasons to Learn Markdown

Writing documentation is fun—really, really fun. I know some engineers may disagree with me, but as a technical writer, creating quality documentation that will help folks has been the most engaging and fulfilling job I’ve ever had. One of the coolest aspects has been using Markdown to write and format almost all of that documentation.

What is Markdown?

Markdown is a lightweight markup language created in 2004 by John Gruber and Aaron Swartz. It creates formatted text via a plain-text editor. Unlike HTML or XML, it is still easily digestible by readers of all backgrounds in its source form. You don’t need to be a programmer to get the gist of things. And although it borrows its syntax from HTML, Markdown is easier and quicker to learn.

The tags—that is, the syntax used to format text (<b>word</b> to bold text, for example)—are simpler than HTML, but they still automatically convert to HTML. So, if you’d prefer, you can still use HTML tags when working with Markdown.

Markdown is used almost everywhere, from GitHub to Slack. It’s the unofficial text writing and formatting standard on big coding sites, like coding repositories. Most engineering readme files are written with and formatted using Markdown. Most text editors accept it as well.

Beyond the fact that it’s easy to use, quick to learn, and easily converts to HTML, Markdown is also pretty futureproof. By this, I mean Markdown will be usable as long as plain text is the official and unofficial standard. It was designed to be quickly parsed and digested as a raw file, but also has its own file extension (.md). Suffice to say, Markdown isn’t going anywhere—especially in the world of engineering and engineering documentation.

Why use Markdown?

I’m answering this question from my perspective as a technical writer, but you can leverage the benefits of Markdown whenever you write online.

1: It’s simple

Markdown is very simple, as far as markup languages are concerned. That is honestly its biggest benefit. It takes maybe 30 minutes to learn and about an hour to become proficient. Another added benefit both within and outside of engineering orgs is that Markdown text is easy to parse and read in its raw form. This is important because both XML and HTML have a learning curve, so folks who aren’t versed in those languages might not be able to read text packaged in either of those markup languages. Markdown fixes that. It is unobtrusive to the actual text so anyone can read text packaged within Markdown’s syntax.

2: It’s a soft introduction to programming

If you’re new to the world of software engineering, Markdown works as an interesting peek into the power of code. Yes, Markdown’s syntax is simple, but if you’ve never coded, even formatting in Markdown might feel like coding. Seeing your formatting come to life on a webpage or text editor is very cool for those new to programming or markup languages, and I firmly believe that it can inspire people to dive deeper into the world of coding.

3: It’s fast

Now, from a technical writer’s perspective, Markdown makes my job easier. I can write with Markdown at a faster cadence than I could with HTML or XML. Plus, I’ve found that Markdown has been an invaluable bridge between engineering and content writing (a massive umbrella that technical writing falls under).

If a subject matter expert (SME) hands me a piece of documentation he wrote for an API process he’s been working on, I can jump right in because, as I’ve said, Markdown (even in its raw form) can be read by anyone. It puts the engineer and myself on the same page, and it keeps us there together. Plus, most Integrated Development Environments (IDEs) feature text edit areas where Markdown acts as the default markup language for writing.

So, from a technical writer’s perspective, Markdown is a writing tool that keeps documentation formatting a breeze, but it also moves us technical writers closer to developers because it allows us to speak (and write) in the same language and use the same basic formatting syntax. And the best, most useful documentation is created when developers and technical writers are on the same page.

4: It’s collaborative

Markdown is more than just a simplified language. The power of Markdown is that it levels the playing field for technical writers and fosters collaboration between them and engineers—especially technical writers without deep, technical backgrounds.

A technical writing organization that sets Markdown as their default markup language for all documentation opens the door for more technical writers to be hired from diverse backgrounds. This is because one can upskill into being proficient with Markdown quite quickly, as opposed to XML and HTML. I like to call it the great equalizer. Documentation, in many ways, is the unsung hero of every product and engineering org. And in the end, it all comes back to Markdown.

Where to go from here

I’ve long been interested in programming, and I’ve learned a lot of programming skills in my free time. But when I knew I wanted to pivot to technical writing, the first thing I learned (and doubled down on) was Markdown. Before I started my career in this field, every engineer and technical writer I talked to recommended it as, literally, one of the first things I should learn. So I did—and I’m so glad!

Now, as I’m sure those who work closely with me know, I evangelize Markdown whenever I’m given the chance—with colleagues, with folks who come to me wanting to transition to technical writing, and with clients. In my eyes, Markdown is the backbone of modern technical writing and documentation, and it isn’t going anywhere. It is the soft standard for documentation in the world of tech and, eventually, I believe it will just be the standard across the board.

Markdown is the future of technical documentation. And as more and more companies, IDEs, and coding repositories use it as the default markup format for editing and writing documentation, that future is starting now. If you’re starting to write documentation or are considering technical writing, I highly recommend learning Markdown. It will serve you well.