I have been looking for exactly this. Will test it out for sure.
On a side-note, mixing serifs and sans in the way the site does looks like something only a mass murderer would do.
Markdoc: Stripe's Markdown-based authoring framework
71–80 of 157 posts
Re: Markdoc: Stripe's Markdown-based authoring framework
#72Earlier quoted context omitted.
Right now we're only using it in our narrative docs ( http://stripe.com/docs ) but we have plans to use it in the reference docs as well.
What powers the API docs ?
It's all custom; the frontend is React and the backend is Ruby. Our plan is to introduce Markdoc as an intermediary step to improve the authoring experience.
Re: Markdoc: Stripe's Markdown-based authoring framework
#73"side-by-side" is a module that seems to be used extensively throughout this projects documentation, as well as in stripes documentation. I don't see where it is defined anywhere, do they have a library of these common helpers? I looked but I guess my searchfu isn't what it used to be.
Re: Markdoc: Stripe's Markdown-based authoring framework
#74See also HedgeDoc https://hedgedoc.org/ which is collaborative and supports tables.
Re: Markdoc: Stripe's Markdown-based authoring framework
#75Earlier quoted context omitted.
Would be very cool with some information on how they work with creating the docs, manage them etc.
I agree. Most companies, open source projects, and individual developers find this to be a Herculean challenge. I'd love to know if Stripe has any secrets to keeping their Docs updated. Though, my gut says that they likely just put in the work. Their Docs are incredibly important to their success.
It helps when you have people staffed full time for the work. Stripe views docs as a product, not an afterthought
Re: Markdoc: Stripe's Markdown-based authoring framework
#76I'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?
Hey, I work on the Docs Product engineering team at Stripe and created Markdoc. The scope is somewhat different: Jekyll and Middleman are static site generators that provide a full stack for content publishing whereas Markdoc is a framework for processing Markdown content with custom tags and transforming it into the desired output format. Markdoc can be used inside of a static site generator or a custom documentatio…
way cool! I work at dbt Labs and see a similarity with dbt jinja, where all dbt does is render the jinja tags into "pure" SQL. is this the same thing in that markdoc "compiles" markdoc files into markdown, that then can be used in static-site generators?
Re: Markdoc: Stripe's Markdown-based authoring framework
#77Earlier quoted context omitted.
As an individual developer with many open-source projects, I'm pretty sure that my docs would be better if I had $2+ billion in funding ;)
The odds are deeply against your assertion- If we look at companies with $2b in funding, chances are yours would fall somewhere in the the median range, rather than at the top of the pack.
I think they meant "better than my docs are now with $0 funding" rather than "better than the median company with $2bn funding"
Re: Markdoc: Stripe's Markdown-based authoring framework
#78We get to use Markdoc every day and it is a joy to work with.
Shameless plug: we're looking for someone to come in and a product manager over the Stripe Docs. Imagine working on docs at the company known for docs. Very fun problems.
https://stripe.com/jobs/listing/product-manager-docs/3928998
Re: Markdoc: Stripe's Markdown-based authoring framework
#79I am glad to know there are those that put so much thought into documentation. Documentations is just another service, and deserves all the same methodology: CI/CD, automatic tests, components and reuse, different environments etc.
As far as I can see, you can get similar workflow with combination of existing tools. I created this docker image that combines them for very easy consumption and created thousands of pages of technical, functional and user documentation with it:
Re: Markdoc: Stripe's Markdown-based authoring framework
#80"side-by-side" is a module that seems to be used extensively throughout this projects documentation, as well as in stripes documentation. I don't see where it is defined anywhere, do they have a library of these common helpers? I looked but I guess my searchfu isn't what it used to be.