ReStructuredText vs. Markdown for documentation
One point that's not really touched upon is the fact that it really does matter whether the person writing the documentation is a technical writer or a developer.<p>If you're a tech writer, you're probably interested in using the best tool for the job, because writing documentation is what you do day in, day out.  If ReStructuredText is the most powerful format, then you're going to strongly lean toward that.<p>If you're a developer, however, writing documentation -- while you may recognize its necessity -- is a task that is often a slog.  It's something you do so you can get it out of the way, and you really don't want to spend very much time thinking about the "how."  You especially don't want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.<p>I say this as a developer who is also a writer.  I enjoy writing, but I know many developers don't.  And if Markdown makes it easier for them to write documentation, either because they're already familiar with it or because it's just a simpler format, then I'm all for it, even if ReStructuredText might be a bit powerful overall.