> Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. I'd go so far as to flip th

> Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. I'd go so far as to flip those two. By far, it's more important to ensure that documentation can be easily written (the raisin d'etre of MD) than it is to optimize for the job of the people trying to collate/edit/format/improve/maintain the documentation (something that RST speaks to, primarily). Because the primarily failure mode in this space is not that we have imperfectly edited documentation. It's that we lack docs at all, because the hackers didn't understand the doc tools. In Zephyr, we use RST. And... it's fine. I've made my peace with it. But "please write some docs" is a routine comment in review, and in my experience many-probably-most contributors just don't know how and don't want to take the time to learn. The barrier to markdown would be much, much lower.