The "insanity" of the section characters isn't really … it's just that the adorning character doesn't matter so much. (Other than it has to be the same.)
The picture-of-a-tweet nails it, but the author misses the point. It's not "we have Python devs" it's "reST has the best syntax for extensibility": if you need to start doing some sort of macro or pre-processing, reST's syntax is cut out for that. M↓ is not; you'll need to do it out of band. Or, to put it differently, reST's directives offer extension hooks.
> You’ll need to set up an identity and access management (IAM) service in front of your static website. Unless IAM is your jam, it’s better to avail of a managed service to tackle it.
Honestly, while I think reST has a more cleanly thought out syntax that will allow you to grow the complex use cases docs will inevitably hit … the tooling just isn't as good, IMO. Markdown parsers are prolific … reST … not so much, particularly outside of Python. (And IMO, docutils in Python is not very easy to use if you want fine control over parsing & output. It's there, but just hard to take advantage of.) M↓'s syntax is also somewhat limiting: there's just not a lot it can do. (Admonitions, in particular, are useful in tech docs and missing.) There's always HTML, … but that's just not the same.
From my experience: after a few years working with it I finally realized it's extremely well documented once you understand which document you are looking for and some of the underlying abstraction patterns that reST uses. It's just a badly organized mess that seems unorganized or half-finished at casual glance, because so much of the documentation was almost entirely written for the audience of reST's implementors and extenders, and even should be user-facing stuff like "how to write in reST" assumes low level familiarity with its abstractions and have read the documentation in a different order. (Which also is why it can often look "half-finished", it's assuming you already know the correct order to read it in, which isn't necessarily the order it presents itself as.)
reST actually has a strong enough spec document that you could reimplement it some other language that isn't Python and assume a base level compatibility (very contrary to Markdown's case and many flavors), and the reason there aren't more reST engines/libraries in other languages is as much the network effects of the existing ecosystem around Python-based extensions (and Sphinx) more than anything technical or missing in the specs.
The picture-of-a-tweet nails it, but the author misses the point. It's not "we have Python devs" it's "reST has the best syntax for extensibility": if you need to start doing some sort of macro or pre-processing, reST's syntax is cut out for that. M↓ is not; you'll need to do it out of band. Or, to put it differently, reST's directives offer extension hooks.
> You’ll need to set up an identity and access management (IAM) service in front of your static website. Unless IAM is your jam, it’s better to avail of a managed service to tackle it.
We throw ours behind Github, I think using https://github.com/oauth2-proxy/oauth2-proxy ; then Github is our IAM.
Honestly, while I think reST has a more cleanly thought out syntax that will allow you to grow the complex use cases docs will inevitably hit … the tooling just isn't as good, IMO. Markdown parsers are prolific … reST … not so much, particularly outside of Python. (And IMO, docutils in Python is not very easy to use if you want fine control over parsing & output. It's there, but just hard to take advantage of.) M↓'s syntax is also somewhat limiting: there's just not a lot it can do. (Admonitions, in particular, are useful in tech docs and missing.) There's always HTML, … but that's just not the same.
(I've no experience w/ AsciiDoc.)