3 ms·

Hey, I created Markdoc at Stripe. Back in 2017 when I first started exploring options for improving the authoring experience, my original prototype actually use

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

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