Every few months, it seems a new post decrying the use of markdown for documentation (or other things) rises to the top of Hacker News.
There are often good reasons for preferring a more structured option, like reStructuredText, LaTeX, or Asciidoc. Especially in projects where more formal text is required, or where you need to support specialized and structured text formatting.
But for 98% of software projects (and in my experience, 95% of all other text I've ever written), markdown suffices, and it is truly a low barrier compared to the alternatives. It's basically plain text (which anyone can learn to write in a few seconds) with extra features.
I've written two books entirely in markdown—specifically, LeanPub-flavored markdown—and besides plain text, it is the easiest language for general content authoring.
The fact that Markdown's lowest common denominator is 'I can write plain text,' coupled to the fact that there are very good libraries for markdown in every conceivable language, means it is the simplest way to make sure you have a basic level of maintainable documentation, no matter who contributes to your codebase. Getting people to contribute plain text changes to documentation is a heck of a lot easier than getting people to contribute in a specific format which is less popular and requires more specificity.
All 5,000+ posts on this blog are written in Markdown, and there are times when I drop back to HTML for advanced formatting. No problem. And if you want to mix LaTeX into Markdown, there are ways to do that, too.
The truth is, the simplicity and ubiquity of Markdown is the reason it is the best choice for most projects.
It may not be as fully-featured or structured as [insert your favorite format here], but it's good enough.
Comments
The only problem I have with markdown (or markdown flavours really) is its total lack of expandability. If you want something to say "this is a variable name", then to allow you to format said variable the way you want, you need a new markdown flavour with that hard-coded inside. You want a special "email" class? or a special "twitter post reference" that's fetching the URL and embedding the post in your text? That's again a new markdown flavour. You need to distinguish between "attributes" and "methods" for the documentation of a class? You need yet another markdown flavour... Everytime with a new "creative" syntax... Things like ResT let you define the the semantics of those things and the only thing that needs to be implemented is how that transfers into certain formats (could just be a CSS for HTML). Whereas in markdown, you have to implement a new parser and that formatting logic.
While I agree that it's sufficient or good enough for lots of things, it just lacks the flexibility to be good enough for everything.
ResT has its pain points, but until a markdown flavour introduces ResT-like classes things will still stay hard if what you want is the tiniest amount of customization.