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 thankful to their team for how good their Docs are.
Very cool of them to open source this. Looks great.
Totally agree. What makes Stripe's docs so great is not just the content, but also the structure and embedded functionality. Switching between programming languages is seamless, the examples are pre-populated with data from my stripe account which is immediately meaningful to me.
Any framework that supports this functionality is a great contribution to OS
Unfortunately my experience has been different; I found that Stripe's Go doc doesn't match their API and while searching on it I found that someone else had mentioned that to their personnel over freenode 2 years ago.
So I raised an issue on GitHub[1] on Apr 9 and hasn't been attended to yet.
On a more serious note, Stripe's payment links doc seemed to imply that tax rates are automatically calculated if the tax rates are set(as we do with code when we pass the tax_id), But I found after couple of payments that tax aren't being charged, On conversing on Twitter with the payment links dev I came to realize that the required option was not there for me[2] and then after couple of hours with their support staff I was informed that the options was not available for India as 'Stripe Tax' is a separate product.
Overall, I'm happy with Stripe's tech; at least compared to the other options I have. But their docs have caused me some frustrations.
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.
> I'd love to know if Stripe has any secrets to keeping their Docs updated.
Simple: documentation is part of the "definition of done". This goes for API docs (e.g., editing field descriptions) and integration guides/high-level docs. The feature/project isn't done if no one knows how to use it.
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.
Totally agree. There are other companies, though, that have people staffed for the work and they do not do nearly as good of a job. I shall refrain from naming names. :)
They also treat docs as a way to add detail to and flesh out well-designed products rather than as a way to disclaim and explain things they didn’t feel like or have the resources to fix.
I would describe stripe docs as 'acceptable'. Don't get me wrong, I personally have brought them tons of business and work with their API more than a human should. My only issue is that if you are working with their API, you will discover HUGE gaps if you step outside "the norms". That being said, they are a step above everyone else, which should tell you something. Also, the comment regarding open-source applies 300%.
We 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.
Thanks for posting this. What is a good way for learning about the salary and compensation for this position? Nothing specific, b it just ballpark to determine if there’s basic compatibility before applying.
The title is too specific to get good numbers from googling and I worry that docs product managers wouldn’t make what typical product managers make.
[0]
It's a normal PM position and you'd be in the normal PM salary bands. You'd be my peer. I manage the server-side SDKs, the CLI, the VS Code extension, the React Native SDK, the API upgrade experience, etc. We'd be in the same ladder. (AFAIK there's just one PM ladder at Stripe)
I’m curious how much you’ve actually customised it. Does the docs source still have a resemblance to markdown, or is it more of a react-like DSL by now?
> 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 and flexibility, but at the cost of complexity–content can quickly become as complex as regular code, which can lead to maintainability complications or a more difficult authoring environment.
Just a gentle reminder that docs like code has an actual definition that we can refer to.
When we say treat the docs like code, we mean that you:
* Store the doc source files in a version control system.
* Build the doc artifacts automatically.
* Ensure that a trusted set of reviewers meticulously review the docs.
* Publish the artifacts without much human intervention.
That's not how language works, their phrase (that does not actually have a widely used established meaning) means what they meant, not what you say it means.
Yes, that term does have a widely established meaning within the specific context of discussion, technical writing. If the commentator is unaware of what 'docs as code' means in the context under discussion and meant something different, I encourage them to disambiguate by picking a term not already so defined.
> 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.)
Quick question. How do engineers and tech writers use the "live editor" functionality that seems to be in the open source repo? Do you edit in the live editor and is it set up to update the underlying repo? Or do you just modify the markdoc files in the repo with your own editor?
I am a huge fan of this style of page! is there an OSS example of this in full? I would be very keen to see what goes into making such a dynamic page in markdoc looks like
No idea, but it's worth keeping in mind that documentation isn't always written and edited by developers (because developers aren't always good writers). Maintaining the separation between code and content is a good idea if a company uses technical writers or other non-developer content people.
An alternative point of view from Docs Like Code, p.11
Reasons we treat docs like code
Coders and writers have borrowed tools and techniques from each other for decades. When you look at the history of producing docs and code together, you see that tools were invented specifically to produce docs while coding.
For example, the JavaDoc tool has been available since the first Java release in 1999. Visualizing the code in HTML, providing accessible online docs, and updating the documentation with the code were all keys to its success.
I haven't heard of MDX before, but this looks fantastic. The API looks more intuitive than Markdoc. https://mdxjs.com/ for anyone else wanting to learn more.
If you want to play with MDX without having to set it up, check out https://motif.land. It comes with a collaborative editing environment too, that is incredibly easy to use for authoring markdown (our non-technical folks use it too).
mdx is great, especially if your team is already fluent with react/jsx. You might also be interested in docusaurus https://docusaurus.io/ as it has support for mdx built in.
I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc.
I ended up using Mkdocs Material (https://squidfunk.github.io/mkdocs-material/). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...
Does Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.
Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs.
Thanks. The MkDocs docs looks great. Would you be able to point to a sample (python) repo that has various configs etc that I can tweak? When starting with Sphinx + ReadTheDocs this was the most time consuming part , it took me several hours hunting down various docs and examples.
I recommend checking the list of OpenSource projects that use Material for MkDocs [1], for example FastAPI [2]. Alternatively, you can clone the Material for MkDocs repository, as the docs are built with itself.
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 documentation platform.
Markdoc's syntax and custom tags also take a somewhat different approach than many of the string templating systems that are commonly used in static site generators. Markdoc is not a preprocessor, the tags are treated as a first-class part of the markdown content, which parses into a data structure that can be statically analyzed, programmatically transformed, and rendered into the desired output format. For us, that's React, but it could be raw HTML, Web Components, a slide deck, or whatever else you might come up with.
Do all your extensions to Commonmark enable you to generate semantic HTML/XML that can be processed further down a pipeline with XSLT ? Or is the system used mainly to generate fairly standard HTML ? I'm thinking DITA here.
What are the advantages of integrating templating and markdown like that? If I'm using markdown with nunjucks, for instance, what do I stand to gain from switching to Markdoc?
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?
It’s not. dbt goes out of its way to avoid having to parse SQL into an ast; Markdoc is Stripe going out of its way to parse input to an ast. dbt’s approach is more similar to the ERB system Stripe mentions Markdoc replacing.
Upon further inspection, I think the biggest difference is that Markdoc uses Nextjs which means you can write React right in the middle of your code and import React components. But then again, you have Gatsby that's also based on React and is built for static site generation, and supports Markdown.
OMG. I was just about to start my own Markdown parser because I needed custom elements and I was finding too hard to work with existing "customizable" Markdown parsers.
Also, I needed a React renderer for React-Native and I was also about to write my own.
By the looks of it, I will be able to just use Markdoc.
For my startup, which is built around Markdown notecards[1], we've been using markdown-it, which it seems is also being leveraged by the Markdoc project. So far I've written a couple of extensions for markdown-it and haven't really had any issues.
Hey, if you really want to customize markdown with your own elements and their rendering/templating, check out SGML [1]. It's made for exactly this type of flexible and extensible document apps/sites, even allows custom Wiki syntax rules.
Wow! Was thinking of doing the same because I wanted to include custom HTML elements suck as boxed block quotes in my Markdown documents. So does this solve the problem?
It looks like a static site generator - but at the same time it appears you cannot actually generate a static site from it, but you need to run a node.js server.
What separates this from any of the existing markdown static site generators?
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.
Just to add to that, "normal" markdown (I forget which flavor exactly) is currently used for the text blocks within the Stripe API reference documentation.
Because this seems to be run locally, vs something hosted like a CMS.
You locally have a NodeJS app running, you draft a new page, it renders it for you in HTML/CSS, and then you upload the rendered output to your web server?
It would depend on the use case, but as this looks like it's aimed at a technical audience, you'd generally have some sort of CI/CD pipeline that renders the markdoc on a server and deploys the output accordingly, be it a react app, plain html, etc.
In many cases, authors would probably need to run the toolchain locally so they can preview their changes. But publishing would basically be the same as committing code and having a CI pipeline take it from there
So it’s been a few hours and I really love this library! I integrated it into a React/esbuild application and it is working great. The React/Prism example for code highlighting took a little work. They have an example but it is a little buried. Their example wasn’t working for me but it was enough for me to get my own working without react-prism.
Shameless plug:
If anyone is interested, I published my esbuild plugin so you don’t have to transform on the server if you want to just import a markdown file.
Shameless plug: for REST APIs, I've written a tool called Instaunit which combines HTTP API integration tests with documentation generation, since these two things must always be maintained in lockstep.
It's got a ways to go before it generates output that looks as good as Stripe's documentation, but it makes it dead simple to create API documentation that's guaranteed to be in sync with your service, because it was generated by your tests when they ran.
The documentation does not seem to have any examples of the generated docs, though. I think that would be a good addition, because it’s a good selling point for the project.
(I.e I don’t think I’d go through downloading and running it just to see if the generated documentation is ”good enough”.)
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 markdoc with its own set of non standard extensions. Hopefully rst format can catch up among JavaScript developers.
So far haven’t seen a complete documentation tool like Python Sphinx [1].
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."
While completely true, and I personally prefer markdown documentation (or even just a README.md if I can get away with it), larger projects definitely benefit from rst. You're probably going to end up re-inventing parts of it, like all of these markdown documentation projects do via extensions to the language, or littering your markdown with HTML like <div class="alert alert-info">Note, this feature is only available on processors with SSE2 or greater!</div>.
> As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."
Wikis have an incredibly low bar, and at some point making things easy leads directly to garbage-in-garbage-out disorganization.
Having docs go through the same linting and code review process (which should also be easy!) as code is the way forward for docs longer than a few pages.
Sphinx is excellent and batteries included for this sort of lint process.
The learning curve for RST is generally higher because it does more. You'll notice that Markdown's learning curve goes up quite a bit as they add all the features that RST has. That said, RST has some bad design decisions, but I'd say about 75% of the complexity it introduces is needed, and the 25% is bad design.
If you have to extend Markdown, the battle is lost. The basic core idea, is OK, but as soon as you find yourself needing to do more documenty things (lists with formatting, tables, etc.) its the wild, wild west - different extension standards CommonMark, Github style, etc., editor, or library of choice.
Not to mention all the special-custom-component standards now which require code... the whole point of Markdown was you could just use any old text editor and be just as well off as looking at a prettified version.
You have the higher complexity and learning curve anyways, more, even.
I guess, the bad design decisions in RST are bad, but there are equally bad design decisions in all these new extensions, editors.
Instead of trying use a hammer put in screws, we should just change tooling. If you need document-level formatting etc., plain-text formatting is cool but don't try to be markdown. Use markdown when you just need simple text docs, if you find yourself doing complex stuff maybe you shouldn't be using markdown, or at least not calling yourself "markdown".
I've used RestructuredText quite extensively (my company uses it). I can see why people do not want to use it.
1. The specification for the syntax is decent but not really comprehensive. There's zero chance you could write a compatible implementation from it. To be fair this is true for the original Markdown but I think there's been a lot of effort to make fully defined versions (e.g. CommonMark), but...
2. The only implementation is the Python one. Frankly Python sucks. The Docutils code has no type annotations so good luck reading it, which you will have to do because...
3. The actual Docutils API is very badly documented. This is easily the biggest flaw. I have implemented a couple of custom directives for my company's docs and it was extremely frustrating to get it working. Pretty much down to using grep.app to search for examples of other random people that have figured it out.
So I would strongly recommend not using RST. I've been wondering what would be better for a while - normal Markdown is just not rich enough for good docs. This looks pretty nice though.
Latex output is nice, but not really super important in 2022 and definitely not worth the flaws of RestructuredText.
At this point using rst is like advocating for Subversion instead of Git(hub). (Which is actually a good metaphor considering where docutils is hosted...)
I say this as a (former) committer to docutils.
The LaTeX support is ok in rst if you want to create something similar to a Word document. If you actually wanted to print a book, you need to use something like my tool, rst2nitrile.
The Python documentation folks seem to be interested in abstracting Sphinx to markdown as well with MyST...
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 web UI/editor built into the binary. Oh, and if it could manage multiple documents and versioning that would be great too. Looking for a Fossil SCM kind of feel?
Closest thing I've used would probably be LyX but that's almost too capable!
I do appreciate this is a really hard thing to do and I'm wondering what toolchains other people are using?
Emacs org-mode with babel for executing code blocks to generate the diagrams prior to exporting to html/pdf is my flow for this. It still has a steeper learning curve for non-technical users, but if you use post-commit hooks you can have people just make changes that way and let the scripts do the work.
A few folks recommended Quarto to me when I asked about current recommendations recently. My main goal is physical books and that doesn't seem to be a first class citizen anywhere. Looking through Quarto, I can't find reference to markdown syntax for index entries (which indicates that they don't support it.)
Also, I'm heavily biased, but based on my experience I will need to hack whatever tool and I'm not really interested in hacking JS/TS. (My whole reason for getting rid of my rst based tooling is to simplify and sticking in Python simplifies my life, coding in JS/TS not so much.)
I'm also very interested in physical books. Can you point me to anything that supports index entries well, regardless of the language they are written in?
I certainly agree about expecting to need to hack, whatever the tool.
I got kinda intimidated with the Asciidoc toolchain that I instead just wrote a bit of Clojure to call the Java AsciidocJ API. A tiny script that did what I want (make Reveal slides) and it's simple/straightforward and I guess crossplatform :)
There is also Orgmode and Texmacs - but I don't really like that the markup is kinda "locked" to an editor. For instance I've done stuff with Orgmode for ages, but it breaks between Emacs major versions and you can't really export it without having Emacs. I also feel like I'm in effect locked into the platform
Texmacs actually looks fantastic, but I'm nervous putting all my beans in that basket
I've created a VS Code extension that provides a live Pandoc preview with scroll sync and support for executing code: https://marketplace.visualstudio.com/items?itemName=gpoore.c.... Adding support for diagrams would just be a matter of creating a config file specifying the diagram executable and command-line options.
Last week I ported my static physical book building tooling from rst-based [0] to markdown (pandoc filter) based.
I've used my rst tooling to publish many books (like Effective Pandas) and am wanting to drop rst in an effort to simplify my life. My pandoc toolchain is not in github yet, but preliminary exploration validates that I can publish my next physical book with it (with things like front matter, indices, etc).
In the process I messed around with MyST and mistletoe. I dropped MyST because it was evident I would need to mess around with Sphinx again. Been there done that. Too much abstraction.
Mistletoe would have worked too (I need to create custom fences/markup for a few features) but I wanted to see if I could do it with Pandoc.
The Pandoc distinction between Blocks and Inlines is annoying as is the requirement to handle everything at once. With Pandoc, you only get notified at the start of an element, not the end which probably complicates it a bit more than Mistletoe would have.
(I still need to port my slide generation tooling and will probably use mistletoe for that. For epub generation I think I will stick with Pandoc.)
Any reason it is done that way, rather than specifying the diagram in the source of the document using mermaid, pikchr, etc? Even inlining the SVG seems like it would be better for keeping everything together.
Good question. You are right in that it is implemented as a mapping from type → SVG in the Markdoc docs site. However, diagrams don't need to be implemented this way.
Interesting. Thanks for the reply. I'm trying to understand what it would be like to adopt Markdoc as our internal documentation system. I didn't like the "spooky action at a distance" of defining diagrams far away from the text, so I'm glad to hear it's not usual practice :-)
I 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:
How does this compare to DocFX? One thing I think Microsoft does very well is the Azure documentation. It's consistently structured across services, but even better, it's also all just a bunch of Markdown and for any page, you can open a Github issue right from that page. And because it's in Github, you can see the history of a page, which has been helpful to see when options change or when limitations were clarified.
I think MSFT just uses stock DocFX for the Azure docs site, but I'm not sure.
Does this have functionality to auto-generate docs from (python) docstrings? Currently using Sphinx with RTD (ReadTheDocs) theme for this, and quite happy with it, though the setup took a lot of hunting around for examples. Wondering if this is the best auto-doc approach for python these days. For context, I am developing a code base with the intention of later open sourcing it, so wanted to have it properly documented from the start.
I'm a bit confused. Following the React tutorials https://markdoc.io/docs/render#react I was able to render my own react components on custom tags, which I wanted. Nice! But I'm not being able to define how to render my own components for Markdown tags like paragraph or heading :(
How well does this scale to hundreds of pages? I found Jekyll and others can start to slow down here during page generation where it can take several seconds to generate not that many pages, especially if you're using a lot of template features. It's part of the reason Hugo is my default as it's so fast.
"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.
The landing page uses root-relative links and the FAQ/examples don't seem to cover links in depth.
I like relative links because my editor (VS Code) will auto-complete relative links... but many Markdown-based tools don't handle the Markdown-source-to-output-HTML translation.
This looks nice but you might want to have an example of the custom syntax on the front page because as far as I can tell that is the main thing this adds, and currently the front page doesn't make it sound different to anything else.
Another small bug, the ::selection colour in CSS matches the yellow background on your homepage so if you select text there (in the 'Get started quickly' bit) you can't see what you've selected.
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.
Very cool of them to open source this. Looks great.