Stripe docs are a marvel, and every developer who’s had to deal with them knows it. After years of painful PayPal interactions, I remember the amazement and the feverish grin on my face the first time I landed on their API reference. Stripe API is beautifully designed, but it’s the combination of good design and excellent documentation that paved Stripe’s fulgid success.
A few days ago, they unexpectedly released MarkDoc, the “powerful, flexible, Markdown-based authoring framework” they use internally to build their documentation. I skimmed through it only rapidly and, unsurprisingly, got a great first impression.
Fabrizio Ferri Benedetti, who knows better than me about docs, published a solid first-glance review of MarkDoc that I think is worth reading. Spoiler alert, I’m quoting below his excellent closing thoughts.
The secret to Stripe docs does not lie in superior tooling or magical markup variants: rather, the reason for their success must be found in the quality of their docs team, whose information architecture needs caused Markdoc to happen. This is the kind of magic that happens when you provide enough technical resources to your technical writers and trust them to do the right thing.
Update: MarkDoc even received John Gruber’s endorsement. That’s quite an achievement as Gruber is renowned for dismissing most Markdown extensions.