31–40 of 157 posts
What separates this from any of the existing markdown static site generators?
Stripe's Docs have been best-in-class for a long time. Obviously, the care and human hours they put into their upkeep is the main reason for the Docs being so good. But, as with any creative endeavor, the tools matter. If the Stripe team didn't like the content management system they used to keep the Docs up-to-date they'd be less likely to do it. As someone that has used their Docs for hours and hours and hours I'm…
I don't understand how this is fundamentally different than MDX, which can already mix React components within Markdown. We used it to build the Streamlit docs. I assumed this is how everyone was doing documentation: https://github.com/streamlit/docs
They explain the difference in an FAQ. https://markdoc.io/docs/faq > The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data). > Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power an…
Stripe's Docs have been best-in-class for a long time. Obviously, the care and human hours they put into their upkeep is the main reason for the Docs being so good. But, as with any creative endeavor, the tools matter. If the Stripe team didn't like the content management system they used to keep the Docs up-to-date they'd be less likely to do it. As someone that has used their Docs for hours and hours and hours I'm…
Would be very cool with some information on how they work with creating the docs, manage them etc.
Earlier quoted context omitted.
I'm an engineer on the Docs team at Stripe. Can you say more about where you're seeing the animation and what it looks like?
Here's a picture of one weird animation, looks like others are speaking to something else though. It looks like the "Try it out" is chasing the mouse, but perhaps someone tried to get a bit too fancy with it. Any mouse movement that is slightly irregular (speed, circular motion, etc.) makes for really wonky animations. https://imgur.com/a/X4cZYaM
Good for people who like to work with non-standard markdown. Not sure why companies do not use RestructuredText (rst), which is a proper specification [0] and has been very successful in the area of documentation. In order to generate a print quality documentation from this markdoc format will be a huge task. RestructuredText already has strong support for Latex output. Now people have plain markdown, gitbook and now…
As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."
Does anyone know of tooling like this but not for only making websites? I have an asciidoc based chain that mostly works for generating both PDF manuals and standalone html docs but it's a bit of a faff to install and set up especially for non-technical users. My dream is something like pandoc but with one or more diagram libraries integrated, native PDF output and all wrapped up in a single binary, maybe with a nice…
Earlier quoted context omitted.
They explain the difference in an FAQ. https://markdoc.io/docs/faq > The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data). > Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power an…
> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control". > content can quickly become as complex as regular code Okay, but has that actually happened in practice?
Before we built Markdoc, our documentation was powered by ERB (embedded Ruby templates). Having content mixed with arbitrary code made it incredibly hard to reason about either. Because Markdoc is a declarative language rather than imperative, there's no intermediate state to keep track of, making things easier to follow.
At Stripe, both engineers and tech writers contribute to documentation. Markdoc makes things easier for everyone by keeping the content separate from the code, while still making it possible to build more interactive experiences when you want to. (For example, our integration builder [0] is also powered by Markdoc.)
Good for people who like to work with non-standard markdown. Not sure why companies do not use RestructuredText (rst), which is a proper specification [0] and has been very successful in the area of documentation. In order to generate a print quality documentation from this markdoc format will be a huge task. RestructuredText already has strong support for Latex output. Now people have plain markdown, gitbook and now…
I've used both Markdown and RST extensively. I feel RST has a steeper learning curve than Markdown, and that can be an obstacle to a successful documentation culture at an organization. As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."
I'm not sure what the difference is between this and a bunch of other ones like Jekyll or Middleman? Is it in the render phase? What am I missing?