Markdown for documentation: 6 pros and 5 things to consider

Technical documentation is a demanding discipline, be it hardware or software. But choosing the right authoring environment is a craft in its own right.

As the world keeps speeding up, documentation tools evolve along with it. New formats come, old formats… sometimes stay. And it’s a good thing! Why? Because it broadens the gamut of your options.

Because sometimes, you need a heavyweight, out-of-the-box solution that just works, like an old V12 engine. But sometimes, what you need is something simple, clever, and tailored to your needs, like a custom bike that you design for free in your own garage.

Why Markdown?

Why bother yourself with Markdown in the first place?

Well, it’s just another content markup language. Except that instead of being packed up to the rafters with tags, it’s stripped down of all the stuff that you don’t actually need. You can find out more about what Markdown is here.

And so, authoring simplicity is one of Markdown’s main selling points. Once you get into it, writing Markdown is way simpler and faster than using any WYSIWYG (What You See Is What You Get) editor like Microsoft Word, or more professional authoring tools like OxygenXML or MadCap Flare.

In this sense, it’s a technical writer’s dream: forget formatting woes and focus on the content itself, without going through the hassle of writing pure HTML.

Markdown: definite pros

Let’s consider some of the benefits that Markdown can bring to technical documentation.

Open format

First of all, Markdown is an open standard, not a proprietary standard. This puts it on par with DITA, XML or HTML, not entrapping you in any single software manufacturer’s ecosystem. You can open .md files with any text editor out there. You can jump between tools and environments. You can do whatever you want!

Quick and easy authoring

The main reason for markdown’s existence is simplicity.

Forget <h1></h1> headings, <a></a> links and <p></p> paragraphs. Need a heading? Write #. Need a link? Write [link-title](link). A paragraph? Just write. Markdown’s learning curve is absolutely minimal.

That’s why it’s not only a favourite of developers and tech writers, but of bloggers and journalists too. And that’s why plenty of popular tools like WordPress, Jira or Confluence often support Markdown notation.

Lightweight environment

While managing your documentation in Markdown often takes you from a single tool to a toolstack (made of several separate solutions working together), there’s a great chance that the ultimate environment you end up with is much faster and more lightweight than any of the traditional, integrated authoring systems. Why?

First, compared to other file types, Markdown files take up very little space, which drives the size of Markdown repositories down.

Authoring simplicity is one of Markdown’s main selling points.

Second, you only use the features that you really need. You probably know the pain of mammoth software tools offering you dozens of features you don’t care about, slowing your machine down, inflating repository sizes, and making things way more complex than they should be. By building your own Markdown toolstack, you keep only what you need.

Customization, customization, customization

Which takes us to the next point: nearly-infinite customization possibilities.

Whatever your documentation needs, there is a way to achieve this. It’s just a matter of time and effort. Compared to integrated authoring environments, you’re no longer tied to a corporate release roadmap. If you need a feature, you add it yourself.

Need Markdown syntax highlighting and Markdown preview in your editor? Reach for Visual Studio Code extensions or Atom packages. Want to quickly view your output locally? Go for a static site generator (SSG) like Hugo which builds your complete HTML site in milliseconds (sic!). Need a completely-customized spelling and style checker? Reach for Vale. And so on and so forth.

• For authoring, you can use any editor you want (for example, Atom, or Visual Studio Code).
• To build your output, use any static site generator out there (for example, Jekyll, or Hugo), or any framework like Gatsby.
• For source control, you’re free to use any version control system (for example, SVN or Git), through any client you like (such as Tortoise SVN or GitHub Desktop).
• Most tools you’ll ever need are cross-platform, which is great news if your team is scattered across Mac, Windows and Linux machines.

Perfect for the docs-as-code approach

Among technical writers, Markdown is often known as the developers’ choice.

The reason is not only its simplicity, but also how well it suits the so-called docs-as-code methodology, in which you treat your documentation in exactly the same way as you treat your code, sometimes even keeping it in the very same repository.

The docs-as-code approach creates a whole spectrum of possibilities:

• Easy co-operation and better understanding between authors and developers.
• Automatically-generated (i.e. automatically updated) code samples and API reference topics.
• All the benefits of the Continuous Delivery (CD) approach, such as fast publishing and frequent updates.

It’s like bringing your technical authoring team and your software team together.

$$$

Last but definitely not least, most tools that you’ll ever need to set up your Markdown authoring environment are free and, quite often, open-source. To address one common concern, that doesn’t have to mean a lack of quality – 3di frequently use Microsoft’s Visual Studio Code, a respected (and stable!) editor which costs zero to download and use.

Markdown: things to consider

Sounds good so far? Because it is. That said, there are a few things you definitely need to consider.

Tool vs toolstack

As you may have noticed so far, organizing your own Markdown authoring environment boils down to this: you end up with a hand-picked collection of separate software packages (as integrated as they can be), rather than one single program to rule them all.

In other words, instead of a single tool, you’ve got a toolstack. This situation has its upsides (freedom of choice, unparalleled customization, being cross-platform, no corporate dependency etc.), but, like anything else, it comes at a certain cost.

For example, consider these aspects:

• Maintenance – Each element of your toolstack has its own dependencies. This, in theory, may mean more maintenance (for example, instead of updating a single application, you’ll need to update a few separate applications and packages).
• Onboarding new authors – With a custom toolstack, onboarding a new author will probably take more time than buying a new licence and installing a single tool.
• No corporate support – Freedom from corporate ecosystems means no official customer support. You’re free to do what you want, but when something breaks, it’s up to you to fix it (or lean on the open-source community).
• Fewer out-of-the-box features – Like automated link updates, snippets, variables or reports. You could do it all, but you need to set it up first (or have someone else build it for you).

Setting up

Building a custom vehicle in your garden shed takes more time and effort than buying a new Chevy. Likewise, setting up your own, custom authoring environment will probably take more time and effort than subscribing to a ready-made authoring ecosystem.

For the time and effort part, you can outsource the work to 3di, as we’ve already put in the legwork figuring out Markdown toolstacks.

Markdown comes in many flavours

As with many open standards, Markdown has lived to see several different versions, usually called flavours (although there are emerging standards such as CommonMark).

Although the general air of simplicity remains the same for most Markdown flavours, differences can be annoying when you’re trying to migrate your content.

For example, the popular readme.io documentation tool allows you to export content in Markdown. In theory, it sounds great. In practice, the exported Markdown is so tailor-made for readme.io that migrating it to another flavour, like the popular GitHub Flavored Markdown, is not as simple as it sounds.

Markdown doesn’t fit every scenario

As you probably noticed, Markdown sounds great in the context of software documentation.

Is it good only for documenting code? Definitely not, it’s versatile. But there are situations where Markdown is probably not the best choice:

• Single-sourcing – If you need to publish your documentation in multiple formats (for example, both PDF and HTML), a dedicated single-sourcing tool like MadCap Flare may turn out to better suit your needs.
• Complex conditioning – If your documentation needs complex conditioning features (because, for example, it’s meant for dozens of different audiences, and it’s processed through a large, multi-market localization pipeline), setting up a custom Markdown environment may be quite a challenge.
• Page Layouts – Markdown is generally considered a bad choice for complex page layouts. Of course, anything can be done, but if you’re into printing elegant paper materials with just a bit of HTML on top of it, Markdown may not be what you’re looking for.

Markdown is not a deus ex machina

Finally, there’s a general point that should be made in every discussion about authoring tools: if you can’t write, a custom notebook and golden pen won’t make you a writer. If your content is rubbish, switching tools (or, at least, switching tools alone) is not the solution. If you’ve got bad content, bad processes, bad (or no) authors, no tool (or toolstack) will help you, no matter how good it is.

Should I move my docs to Markdown?

Our discussion leads us to the central question: does writing your documentation in Markdown solve more problems than it creates?

The answer is, as always: it depends.

You should definitely consider Markdown if:

• You’re documenting software – be it end-user documentation or developer documentation.
• You care mostly (or only) about HTML output.
• You’re creating a developer portal.
• You know you’d benefit from the docs-as-code approach.
• You’ve got resources to set up your environment, or you know where to look for help.

As always, you need to carefully consider your own documentation needs. Although Markdown toolstacks are a perfect solution for simple software documentation projects, they also scale up very nicely, especially if you’re sure that you can depend on your authors, or if you’ve got a company like 3di to take care of your content!