I can appreciate that Markdown has flaws, and I totally agree with the benefits of using something more structured.
… but I really, really, really hate writing ReST. 
.
I’m not sure how to reconcile these things. It’s hard enough to get people to write documentation already, the more complex we make it, the less people will do it.