I think the problem here comes in disagreement over the meaning of "documentation". When we talk about documentation for a program, do we mean the man pages? Th

I think the problem here comes in disagreement over the meaning of "documentation". When we talk about documentation for a program, do we mean the man pages? The README? The help docs? The API specifications? Or a long-form document or manual describing the use of the program, such as 'The C Programming Language' or the Camel books? For all of the preceding except the long-form document at the end, I'd say Markdown is a perfect tool. It's portable, it's readable as-is, and it's supported on a variety of platforms including all the various git hosting platforms with native parse-and-render. That makes it the perfect tool for straightforward, uncomplicated documents. For more complicated, formally structured documents, however, Markdown is awful. I've worked on a number of structured documents like public standards docs, procedures docs, and formal specs in Markdown, and they're a pain in the neck. Without using one of the less portable variants like Kramdown, you quickly find yourself having to work your way around the lack of formatting in table cells or specific list-numbering (or lettered lists at all), and so forth, and the less-portable variants mean you suddenly have to worry about your publishing/rendering chain to make sure everything supports what you're using in the form you're using it. The rubric for me has been this: if the way the content looks/is structured on rendering matters, use one of the more structured tools like AsciiDoc or even Word. If the presentation of the content isn't as crucial, Markdown is a perfect tool (and makes a good default!).