A few of these are good arguments, but a few are not. You're right that Markdown is very easy to remember and you don't need to refer to documentation much (if

A few of these are good arguments, but a few are not. You're right that Markdown is very easy to remember and you don't need to refer to documentation much (if at all). It's also very simple and encourages document simplicity. I like Markdown for personal note keeping. And reading Markdown is not much different from reading But you shouldn't use Markdown just because it will stop your colleagues from using other suboptimal document stores. If you're writing documentation you should do it the right way, which is not by offering a poor tool to curb the use of an even worse tool. That's not a professional and scalable way to find a robust documentation solution. That argument would hold up better for a use case like internal documents, in my opinion. Likewise other documentation formats suggested in the article can be source controlled and diffed - there's no reason why you can't use reStructuredText in this way, for example. And there are also heaps of converters for these suggestions, but unlike Markdown their conversions to HTML will be common and well-specified :)