3 ms·

I've always loved Stripe's interactive documentation, wondered how they did it and hoped they'd open-source it. I totally missed the news that they did back in

I've always loved Stripe's interactive documentation, wondered how they did it and hoped they'd open-source it. I totally missed the news that they did back in May. Now, it seems that 99% of documentation tooling advertised is Markdown based; and e-v-e-r-y time I see this on HN I wonder why AsciiDoc[0] isn't more prevalent than Markdown. AsciiDoc is older than Markdown and out of the box supports things that Markdown doesn't, which has led to a proliferation of Markdown flavors that remind me the web browser experience of the 2000s. It is Stripe's documentation that led me a few years back to look into replicating their documentation, particularly the interactive part of it. While I wasn't able to find any tool out there that did this out the box, that's how I found about AsciiDoc in the first place, and then Antora. This tool, Antora[1], is based on Asciidoc and allows you to create amazing documentation websites. A while back I experimented and wrote a PoC of a plugin for Antora that made my documentation interactive. I also believe that AsciiDoc is what O'Reilly authors use to write books (edit: it is one of 3 languages they [2]use: AsciiDoc, HTMLBook, or DocBook XML) I wish AsciiDoc was more commonly used. [0]: https://asciidoc.org/ https://asciidoc.org/ [1]: https://antora.org/ https://antora.org/ [2]: https://docs.atlas.oreilly.com/index.html#what-is-atlas-DNIRua https://docs.atlas.oreilly.com/index.html#what-is-atlas-DNIR...

segphault 4y ago
Hey, I created Markdoc at Stripe. Back in 2017 when I first started exploring options for improving the authoring experience, my original prototype actually used AsciiDoc (via AsciiDoctor). I had a lot of trouble getting buy-in for AsciiDoc from the users, who universally preferred Markdown, and their feedback is what ultimately led me to create Markdoc instead. AsciiDoc gets a lot of things right, but it also has a lot of syntactic complexity and idiosyncrasies that were challenging for our documentation contributors. In documents with structural complexity, it becomes unwieldly very quickly. For example, having to vary the length of the delimiter line when nesting delimited blocks[1] is pretty arcane and leaves a lot of room for errors to creep in when reordering pieces of content. Even though AsciiDoc's extensibility model was compelling to us, it's really not designed for the kind of deeply-nested hierarchies that we needed to be able to express things like our integration builder[2] UI. Anyhow, we have a section in our FAQ[3] that provides more context about why we didn't choose AsciiDoc. I remain a fan of AsciiDoc even though it didn't fully meet our needs, and Markdoc was definitely influenced by the things that we thought AsciiDoc got right. [1]: https://docs.asciidoctor.org/asciidoc/latest/blocks/delimited/#nesting https://docs.asciidoctor.org/asciidoc/latest/blocks/delimite... [2]: https://stripe.com/docs/payments/quickstart https://stripe.com/docs/payments/quickstart [3]: https://markdoc.dev/docs/faq#why-not-asciidoc https://markdoc.dev/docs/faq#why-not-asciidoc
- gouggoug 4y ago
  I've faced the same issue regarding buy-in. For some reason, lots of users flat out refuse to use asciidoc. I think this reaction is purely anxiety around having to 1- learn something new (a new language) 2- to do something that most people find unpleasant (writing documentation). > but it also has a lot of syntactic complexity and idiosyncrasies I don't think that's true; for basic usage, which is probably 90% of what people use, Markdown and Asciidoc syntax are basically the [0]same (AsciiDoc is also compatible with Markdown's syntax) For advanced use, Markdown syntax has to be augmented via one of the many "flavors" (i.e. no real advanced features out of the box) and these flavors usually mean typing raw HTML directly in the documentation. Asciidoc advanced syntax on the other hand is available out of the box for whoever wants to use it, but you don't have to use it. [0]: https://asciidoc.org/#compare https://asciidoc.org/#compare
subpixel 4y ago
AsciiDoc's flagship feature is the include directive (think partials). GitHub rendering doesn't support it. On GitLab you are limited to ~30 includes, after which your document just spits out source. So in most cases, you can't preview AsciiDoc files that use the include directive without cloning the repo and previewing it locally. When you take away the include directive you have a less elegant syntax that is harder for contributors to read, much less adopt. Add to that a very small community and a lack of critical tools. Most glaringly, there is no linter for AsciiDoc. AsciiDoc just doesn't have advantages over Markdown (including partials, as Markdoc and other tools used by IBM and Microsoft allow them). Meanwhile Markdown renders everywhere, and it's highly legible as source.
- gouggoug 4y ago
  > AsciiDoc's flagship feature is the include directive (think partials). GitHub rendering doesn't support it. On GitLab you are limited to ~30 includes, after which your document just spits out source. So in most cases, you can't preview AsciiDoc files that use the include directive without cloning the repo and previewing it locally. Does Markdown support partials/includes, and does Github honor them? I don't believe it does... (I tried googling about it, didn't find anything, but I could be wrong) so not sure how this can be used as an argument against asciidoc. > When you take away the include directive you have a less elegant syntax that is harder for contributors to read, much less adopt. Markdown and AsciiDoc syntax are extremely [0]similar, and AsciiDoc supports markdown's syntax. [0]: https://asciidoc.org/#compare https://asciidoc.org/#compare
  - subpixel 4y ago
    I've used both for a decade or more, and my opinion is that includes/partials is the only thing AsciiDoc offers that even justifies considering it as a markup language for docs. If (big if!) using includes/partials without React is so important you'd consider giving up all the benefits of Markdown. IBM, Microsoft and Stripe all have tooling that enables Markdown includes/partials. None of those will render natively in GitHub or Gitlab - but if you really need that feature you probably don't care as the AsciiDoc support is also so poor. I think if AsciiDoc and Markdown were in the same league from a writing and reading perspective, AsciiDoc might have more traction. Other comments in this thread support the case that it's just harder to write and read as markup. A whole other topic is how Markdown has been adopted by React-driven systems. This just solidifies Markdown's position as the lingua franca.
drcongo 4y ago
I tried Asciidoc last time it got a shout out on here, possibly by yourself. On a totally personal level, I found it really ugly and clunky to write, like going from Python to PHP.
xani_ 4y ago
Markdown (with flavouring, plain one is just too poor) still IMO looks better in its text form, which was main point of it, ASCIIdoc looks a bit worse as pure text (altho not bad). But it is probably just plainly "it happened that Big Things adopted it, so more Big Things saw it and also adopted it"

segphault 4y ago

Hey, I created Markdoc at Stripe. Back in 2017 when I first started exploring options for improving the authoring experience, my original prototype actually used AsciiDoc (via AsciiDoctor). I had a lot of trouble getting buy-in for AsciiDoc from the users, who universally preferred Markdown, and their feedback is what ultimately led me to create Markdoc instead. AsciiDoc gets a lot of things right, but it also has a lot of syntactic complexity and idiosyncrasies that were challenging for our documentation contributors. In documents with structural complexity, it becomes unwieldly very quickly. For example, having to vary the length of the delimiter line when nesting delimited blocks[1] is pretty arcane and leaves a lot of room for errors to creep in when reordering pieces of content. Even though AsciiDoc's extensibility model was compelling to us, it's really not designed for the kind of deeply-nested hierarchies that we needed to be able to express things like our integration builder[2] UI. Anyhow, we have a section in our FAQ[3] that provides more context about why we didn't choose AsciiDoc. I remain a fan of AsciiDoc even though it didn't fully meet our needs, and Markdoc was definitely influenced by the things that we thought AsciiDoc got right. [1]: https://docs.asciidoctor.org/asciidoc/latest/blocks/delimited/#nesting https://docs.asciidoctor.org/asciidoc/latest/blocks/delimite... [2]: https://stripe.com/docs/payments/quickstart https://stripe.com/docs/payments/quickstart [3]: https://markdoc.dev/docs/faq#why-not-asciidoc https://markdoc.dev/docs/faq#why-not-asciidoc

gouggoug 4y ago
I've faced the same issue regarding buy-in. For some reason, lots of users flat out refuse to use asciidoc. I think this reaction is purely anxiety around having to 1- learn something new (a new language) 2- to do something that most people find unpleasant (writing documentation). > but it also has a lot of syntactic complexity and idiosyncrasies I don't think that's true; for basic usage, which is probably 90% of what people use, Markdown and Asciidoc syntax are basically the [0]same (AsciiDoc is also compatible with Markdown's syntax) For advanced use, Markdown syntax has to be augmented via one of the many "flavors" (i.e. no real advanced features out of the box) and these flavors usually mean typing raw HTML directly in the documentation. Asciidoc advanced syntax on the other hand is available out of the box for whoever wants to use it, but you don't have to use it. [0]: https://asciidoc.org/#compare https://asciidoc.org/#compare

subpixel 4y ago

AsciiDoc's flagship feature is the include directive (think partials). GitHub rendering doesn't support it. On GitLab you are limited to ~30 includes, after which your document just spits out source. So in most cases, you can't preview AsciiDoc files that use the include directive without cloning the repo and previewing it locally. When you take away the include directive you have a less elegant syntax that is harder for contributors to read, much less adopt. Add to that a very small community and a lack of critical tools. Most glaringly, there is no linter for AsciiDoc. AsciiDoc just doesn't have advantages over Markdown (including partials, as Markdoc and other tools used by IBM and Microsoft allow them). Meanwhile Markdown renders everywhere, and it's highly legible as source.

gouggoug 4y ago
> AsciiDoc's flagship feature is the include directive (think partials). GitHub rendering doesn't support it. On GitLab you are limited to ~30 includes, after which your document just spits out source. So in most cases, you can't preview AsciiDoc files that use the include directive without cloning the repo and previewing it locally. Does Markdown support partials/includes, and does Github honor them? I don't believe it does... (I tried googling about it, didn't find anything, but I could be wrong) so not sure how this can be used as an argument against asciidoc. > When you take away the include directive you have a less elegant syntax that is harder for contributors to read, much less adopt. Markdown and AsciiDoc syntax are extremely [0]similar, and AsciiDoc supports markdown's syntax. [0]: https://asciidoc.org/#compare https://asciidoc.org/#compare
- subpixel 4y ago
  I've used both for a decade or more, and my opinion is that includes/partials is the only thing AsciiDoc offers that even justifies considering it as a markup language for docs. If (big if!) using includes/partials without React is so important you'd consider giving up all the benefits of Markdown. IBM, Microsoft and Stripe all have tooling that enables Markdown includes/partials. None of those will render natively in GitHub or Gitlab - but if you really need that feature you probably don't care as the AsciiDoc support is also so poor. I think if AsciiDoc and Markdown were in the same league from a writing and reading perspective, AsciiDoc might have more traction. Other comments in this thread support the case that it's just harder to write and read as markup. A whole other topic is how Markdown has been adopted by React-driven systems. This just solidifies Markdown's position as the lingua franca.

drcongo 4y ago

I tried Asciidoc last time it got a shout out on here, possibly by yourself. On a totally personal level, I found it really ugly and clunky to write, like going from Python to PHP.

xani_ 4y ago

Markdown (with flavouring, plain one is just too poor) still IMO looks better in its text form, which was main point of it, ASCIIdoc looks a bit worse as pure text (altho not bad). But it is probably just plainly "it happened that Big Things adopted it, so more Big Things saw it and also adopted it"