I implore you: do not use anything but Markdown in environments where software engineers will be writing and maintaining the bulk of the documentation. I once w

I implore you: do not use anything but Markdown in environments where software engineers will be writing and maintaining the bulk of the documentation. I once worked on the docs team for a large org that used rST/Sphinx. Engineers complained incessantly and it was a constant struggle to cajole them to keep docs up to date. My experience suggests unambiguously that engineers will not take the time to learn a different markup format. They will spend hours or days or weeks learning a new language, deployment tool, protocol, library, etc. But in most cases they will simply refuse to spend one iota of time learning documentation tools. If you think I'm wrong, try making it your day job to get engineers to write rST (or Asciidoc or anything they don't already know).