[hobofan]

Yes, the author conflates two different use-cases.

Markdown is the answer for "how do we enable people that don't want to invest a lot of time into producing content that's somewhat better than plain text?".

It's not trying to solve the problem of "how do we enable people that are willing to invest time into learning to produce the best possible and most structured content possible?" and I doubt that there will be language that will serve both of those use-cases very well.

[mangecoeur]

The problem in practice is that quickly one merges into the other. You start with a markdown readme, then you have markdown documentation for a small project. But then one day you need full documentation for your project with cross links, translations, accessibility. With Markdown you end up bolting these things on and each flavor does it a bit differently.

Perhaps some of the blame can be laid with the poor UX of technically superior systems. restructuredtext (apart from the terrible name) built with Spinx can do impressive things but becomes a huge pain to configure. All the XML-based tools like DocBook are very complete but try to get started actually building something - apart from having to author them in XML (which is already a kind of punishment), then you have to figure out XSLT stylesheets, 2000s-era design Java tools for processing them. And just look at the DocBook landing page! AsciiDoc has improved their onboarding recently but does have the issue of feeling like a markdown-ish alternative that's just a bit different for no clear reason.

[thayne]

> does have the issue of feeling like a markdown-ish alternative that's just a bit different for no clear reason.

Asciidoc is older than markdown. Kind of hard to be design something to be the same as something that isn't invented yet.

[swiftcoder]

One downside here is that as more and more tools focus on the first use-case, people start using those tools by default when they actually fall into the second use-case. And there's often a pretty high barrier to switching once you've produced a lot of content, so a bunch of projects are using the wrong one long-term.

[pas]

Arguably having a ton of hard to write, hard to maintain docs is waaay worse than Markdown that gets attention in PRs (MRs).

Especially that the things in the article seem irrelevant compared to actually adding and handling non-text content IMHO. (Mermaid diagrams for example.)

Sure a validator would be nice, but that's why a simple preview is available in most collaboration platforms.