5 ms·

I honestly don't get why Markdown became preferred in most projects over AsciiDoc.

by chungy 4y ago

wnoise 4y ago
Have you tried to parse it? Even the Swiss army knife of document formats, pandoc, only supports it as an output format.
markstos 4y ago
Because people know and like Markdown. It’s good enough so they don’t go looking for a replacement. Markdown is used enough that you are going to need to know the syntax. So a competitor doesn’t just have to better, it has to have enough additional merits to be worth learning in addition to Markdown.
- nerdponx 4y ago
  AsciiDoctor and Org Mode both have substantial additional merits over Markdown, and have dedicated user bases. The problem nowadays is that of implementation availability.
abathur 4y ago
I suspect a lot of it's inertia from before the choice mattered or was actually reflected on (though I guess there are still plenty of projects changing). It's easy, most projects can satisfice with it, and people on the projects that can't satisfice with it may not think about markup enough to realize they're painting themselves into a corner until they have a big ballast of existing documentation to cope with? I've been fumbling around for how to convey signs that a project may need better tools (https://t-ravis.com/post/doc/what_color_is_your_markup/ https://t-ravis.com/post/doc/what_color_is_your_markup/) but it's been slow-going and I'm bearish on how well ~better-practices will spread.
nerdponx 4y ago
I think this is partly because AsciiDoc has broadly been tied to a single implementation, AsciiDoctor, without a spec, not even a sketch in a blog post like the original Markdown was. It's only recently that AsciiDoc has begun to think of itself as "a markup language" rather than "the markup language used by AsciiDoctor". A spec is apparently WIP. As for why it never gained the memetic popularity of Markdown that might have led to a different trajectory, that's harder to say. The One True Markdown is fundamentally much simpler than AsciiDoc, and consequently much easier to learn, easier implement in JavaScript for live rendering on the Web, and easier to extend with your own opinionated features. So I think it was easy and attractive for various platforms like Hacker News and Github to support it, and this I think had a snowballing network effect. Personally I love AsciiDoc and I think it's the future of technical writing and publishing. It's everything I wanted out of reStructuredText but without its fussy, non-composable syntax. However I don't think that future will become reality until a spec is published that is friendly to implementers other than AsciiDoctor.
- chungy 4y ago
  AsciiDoctor is a second implementation that doesn't even fully compatibly implement the original specification. The original AsciiDoc is pretty well-specified, and it's mostly the plaintext markup of stuff that was intended to go to DocBook, with very little surprises from that. AsciiDoctor pretty much focused on a direct HTML translation and ignored the inconvenient parts. (Some of the inconvenient parts are deprecated syntax that while AsciiDoc's had a replacement for, I've written the old style for ~20 years and when GitHub tries to render a document with AsciiDoctor, oops; sometimes I'll change the document, sometimes I'll decide rendering on GitHub isn't important.)
uvtc 4y ago
> I honestly don't get why Markdown became preferred in most projects over AsciiDoc. I think the primary reason is because Markdown is prettier to read (and also secondarily because it's good enough). There are lots of markup formats, but markdown is probably the easiest on the eyes.

I honestly don't get why Markdown became preferred in most projects over AsciiDoc.

by chungy 4y ago

I honestly don't get why Markdown became preferred in most projects over AsciiDoc.

Have you tried to parse it? Even the Swiss army knife of document formats, pandoc, only supports it as an output format.

markstos 4y ago

Because people know and like Markdown. It’s good enough so they don’t go looking for a replacement. Markdown is used enough that you are going to need to know the syntax. So a competitor doesn’t just have to better, it has to have enough additional merits to be worth learning in addition to Markdown.

nerdponx 4y ago
AsciiDoctor and Org Mode both have substantial additional merits over Markdown, and have dedicated user bases. The problem nowadays is that of implementation availability.

abathur 4y ago

I suspect a lot of it's inertia from before the choice mattered or was actually reflected on (though I guess there are still plenty of projects changing). It's easy, most projects can satisfice with it, and people on the projects that can't satisfice with it may not think about markup enough to realize they're painting themselves into a corner until they have a big ballast of existing documentation to cope with? I've been fumbling around for how to convey signs that a project may need better tools (https://t-ravis.com/post/doc/what_color_is_your_markup/ https://t-ravis.com/post/doc/what_color_is_your_markup/) but it's been slow-going and I'm bearish on how well ~better-practices will spread.

nerdponx 4y ago

I think this is partly because AsciiDoc has broadly been tied to a single implementation, AsciiDoctor, without a spec, not even a sketch in a blog post like the original Markdown was. It's only recently that AsciiDoc has begun to think of itself as "a markup language" rather than "the markup language used by AsciiDoctor". A spec is apparently WIP. As for why it never gained the memetic popularity of Markdown that might have led to a different trajectory, that's harder to say. The One True Markdown is fundamentally much simpler than AsciiDoc, and consequently much easier to learn, easier implement in JavaScript for live rendering on the Web, and easier to extend with your own opinionated features. So I think it was easy and attractive for various platforms like Hacker News and Github to support it, and this I think had a snowballing network effect. Personally I love AsciiDoc and I think it's the future of technical writing and publishing. It's everything I wanted out of reStructuredText but without its fussy, non-composable syntax. However I don't think that future will become reality until a spec is published that is friendly to implementers other than AsciiDoctor.

chungy 4y ago
AsciiDoctor is a second implementation that doesn't even fully compatibly implement the original specification. The original AsciiDoc is pretty well-specified, and it's mostly the plaintext markup of stuff that was intended to go to DocBook, with very little surprises from that. AsciiDoctor pretty much focused on a direct HTML translation and ignored the inconvenient parts. (Some of the inconvenient parts are deprecated syntax that while AsciiDoc's had a replacement for, I've written the old style for ~20 years and when GitHub tries to render a document with AsciiDoctor, oops; sometimes I'll change the document, sometimes I'll decide rendering on GitHub isn't important.)

uvtc 4y ago

> I honestly don't get why Markdown became preferred in most projects over AsciiDoc. I think the primary reason is because Markdown is prettier to read (and also secondarily because it's good enough). There are lots of markup formats, but markdown is probably the easiest on the eyes.