Get the top HN stories in your inbox every day.
cdevroe
wolframhempel
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
Abishek_Muthian
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.
[1] https://github.com/stripe/stripe-go/issues/1447
[2] https://twitter.com/joshuaackerman/status/144759582096702259...
oellegaard
Would be very cool with some information on how they work with creating the docs, manage them etc.
cdevroe
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.
clintonb
> 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.
threepio
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 ;)
jb3689
It helps when you have people staffed full time for the work. Stripe views docs as a product, not an afterthought
eek2121
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%.
undefined
aquilaFiera
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.
https://stripe.com/jobs/listing/product-manager-docs/3928998
prepend
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]
[0] https://www.glassdoor.com/Salary/Stripe-Product-Manager-Sala...
aquilaFiera
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)
9dev
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?
Job sounds super fun by the way :)
nkohari
The Stripe docs use a library of a few dozen Markdoc tags. While the tags are different, the articles on https://markdoc.io are pretty similar to those in the Stripe docs. For example: https://raw.githubusercontent.com/markdoc/docs/main/pages/do...
etchalon
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
Veen
They explain the difference in an 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 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.
pomber
I like that they write it as a trade of. I think I still prefer the maintainability complications of "docs as code" https://www.youtube.com/watch?v=xEu3t-KJVVg
docmechanic
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.
Docs Like Code, Anne Gentle, p. 10
maxerickson
The quoted text says "as" and clearly intends that meaning.
ipsum2
> 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?
nkohari
> 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.)
dragonwriter
> React is also a "fully declarative approach to composition and flow control".
MDX, which allows embedding JSX isn't fully declarative, since arbitrary imperative structures can be used in JS blocks in JSX.
Veen
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.
ipsum2
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.
ankrgyl
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).
dsmmcken
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.
_miau_hoch2
For anyone looking for a doc generation tool:
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 ...
d4rkp4ttern
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.
squidfunk
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.
[1]: https://mkdocstrings.github.io/
d4rkp4ttern
Another important requirement for me is support for Math notation in docstrings and elsewhere. Looks like MkDocs supports mathjax?
https://squidfunk.github.io/mkdocs-material/reference/mathja...
d4rkp4ttern
This is great, thank you.
armchairhacker
After looking through Docusaurus, GitBook, and a few others, I also ended up with mkdocs and github pages. It’s very straightforward to setup.
evolve2k
I spent 6 months assessing the options came down to ‘Material for Mkdocs’.
ksajadi
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?
segphault
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.
euroderf
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.
bccdee
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?
data_ders
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?
riwsky
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.
ksajadi
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.
andrerpena
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.
Thank you Stripe!
fastball
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.
tannhaeuser
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.
[1]: http://sgmljs.net
kyawzazaw
A bit of a tangential question.
What kind of project or business that you run that you need it?
How much hours do you estimate it would have taken you?
SneakyTornado29
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?
Duhck
We use Remark, and given the ability to leverage AST, its pretty much limitless in terms of customization
oellegaard
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?
polutropos
This is amazing. Does this power the Stripe API reference pages? https://stripe.com/docs/api
Or is this only for https://stripe.com/docs, https://stripe.com/docs/payments, etc?
nkohari
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.
alberth
So what's the workflow for this?
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?
(Sorry for the naive question)
harg
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
verdverm
you definitely need something around this, it lacks a lot of the other features in Hugo or Jekyll
Might be easier to graft into an existing, dynamic CMS (that uses a DB)
todd3834
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.
bww
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.
uvesten
Looks neat!
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”.)
dragonsh
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].
[0] https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...
cubes
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."
TkTech
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>.
zdw
> 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.
ericholscher
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.
smaudet
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".
IshKebab
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.
Do not use RestructuredText.
euroderf
Several previous discussions at HN have suggested that AsciiDoc is better to work with than RST.
__mharrison__
Funny you say that. I spent most of last week porting some of my rst based book authoring tooling to md/pandoc.
__mharrison__
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...
rst is a dead end at this point.
Get the top HN stories in your inbox every day.
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.