Hacker News Reader

Comment by cdevroe | Hacker News Reader

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.

View on HN

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.

[1] https://github.com/stripe/stripe-go/issues/1447

[2] https://twitter.com/joshuaackerman/status/144759582096702259...

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.

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"

Maybe you'd have $2+ billion in funding if your docs were better!

It helps when you have people staffed full time for the work. Stripe views docs as a product, not an afterthought

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'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.

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%.

It seems that many Stripe team members walk the HN halls, if you were to give a few examples of the "HUGE gaps" you mentioned they might fill them in.

Yes—would like to hear more about how we can fill in the gaps. (Can also email me directly at edwin@stripe.com.)

Reply on news.ycombinator.com