You are here: Home » NewsFeeds » Why You Shouldn’t Use “Markdown” for Documentation

Why You Shouldn’t Use “Markdown” for Documentation

“Markdown” is the most commonly used lightweight markup language on the internet.
It is great for a subset of tasks,
mainly blog posts and commenting.
lately it has been adopted by the technical writing community as a solution for writing documentation.
I’d like to lay out the main arguments that I have against Markdown.
Hopefully this will be useful in helping you decide whether it’s a good fit for your organization.
If you are considering Markdown,
I hope that you also look at Asciidoctor and Sphinx.
I find them to be much better toolsets for writing documentation.
Markdown is often chosen because it’s viewed as a simple approach that handles the basic cases well.
Developers prefer it because GitHub supports it,
though GitHub supports 9 different markup languages,
including Asciidoc and reStructuredText.
As documentation grows from a few pages into a large set of documents,
Markdown quickly falls over and becomes a liability instead of a benefit.
I’d like to explain a bit more about


Original article