[Not the GP, but 100% in agreement with them, except that we abandoned updating our integration.]
I'd really like to hear where we can improve the docs.
IMHO, the fundamental problem is that as the data model and API have become more complicated, the explanatory documentation has become less coherent. It feels like jumping around a Wiki now.
More specifically, we couldn’t find anything to show us the big picture of how SCA actually works with Stripe’s system. We also couldn’t find useful end-to-end walkthroughs with code samples to learn by example, hence my suggestion in the other comment you replied to. Lacking a frame of reference from one source or the other, all the detailed documentation about Stripe.js and APIs doesn’t help very much, because you don’t know what you need to look up in the first place or how anything fits together.
This was compounded in our case because after spending considerable time swapping messages with Stripe support, in which we did explain that we’d read all of your documentation and we did also describe our (very simple) existing subscription set-up process in terms of specific Stripe.js and API calls, the responses were just boilerplate references to documentation pages we’d already read. Of at least five different people from Stripe who replied to me over more than two weeks, not a single message mentioned any specific function in Stripe.js or the API or any specific webhook, despite several explicit requests and sending specific details on that level from our side at Stripe’s request.
To put this in perspective, please consider that when we first integrated with Stripe, it took one Stripe.js call, usually one API call and one webhook to tokenize card details, set up a Customer and Subscription with that card, and then act on each successful payment. I wrote that code myself in less than an hour, and I think it was described start-to-finish on no more than two or three pages on Stripe’s documentation site.
At the risk of making this comment antisocially long, but with the suspicion that we have not been the only ones following this path, I’ll describe what happened this time instead. The first of several links I was sent by Stripe support in one of those emails went to a page about saving card details for later (https://stripe.com/docs/payments/cards/saving-cards-after-pa...). Within just the first step of that page, there are at least six different concepts we hadn’t previously used in our integration that were mentioned, most of them without any sort of introduction, definition or link. Some of these are clearly very important concepts in SCA world, like a new PaymentIntents API and distinguishing on-session from off-session payments. OK, so we need to learn about those. Off we go to the API documentation, where we do find PaymentIntents, which in turn refers us immediately to the PaymentIntents API explanatory page (https://stripe.com/docs/payments/payment-intents/creating-pa...). This gives us a general idea of what PaymentIntents do (remember, when we integrated before, you didn’t even have concepts like Invoices in your API) but then starts talking about manual and automatic confirmation. So before we’ve finished reading the introduction on that page, we already have two more new concepts, and there’s a third link to a comparison between them, but that refers to one-time payments and we’re trying to set up a subscription, so now we’re jumping context and don’t know whether what we’re reading is actually relevant to our use case or not.
That last paragraph could continue for literally several more days of finding our way around, often going in circles. We’ll later be confused by the difference between PaymentIntents and SetupIntents, several similarly named but apparently quite distinct functions in Stripe.js v3 that might replace the old call to create a token, the difference between a source and a payment method, which actions happen synchronously and which are or might become asynchronous in the new world of PaymentIntents and SCA, and many other such questions. We’ll also wonder how any of this fits in with things like Dunning, which was the other big improvement we had hoped to make back when we first started reading about the latest APIs and contacted Stripe support for advice. One important thing you’d notice by the end of the story is that at no point did we ever discover what triggers step one on that very first documentation page to start with — is it a replacement for the old tokenization using Stripe.js, a replacement for the old Customer.create API call, something we have to do in addition to those things at some point?
This comment is already far longer than I had intended, but I hope that gives you some idea of how the current documentation and support systems are not working as well as they used to, from the perspective of a long-time Stripe merchant just trying to update their integration to the new APIs to maintain the equivalent of functionality we already had.
If I were tasked with improving the docs then I would start with an exercise to identify all of the explanatory pages for the new PaymentIntents API, SCA migrations, Dunning, and anything else related. Then I’d get someone, preferably someone who doesn’t already intimately understand how SCA works and Stripe’s API, to go through and highlight every concept or technical term that hasn’t yet been explained before it’s used. I suspect that would identify many points of potential confusion, but with several recurring themes. Next, I’d take a step back, look at how SCA works, look at how the Stripe data model and new APIs work, determine which are the foundational concepts that keep coming up but haven’t been explained first at the moment, and then write a one-page introduction to the big picture and how these concepts fit together. That is the key page that is completely missing at the moment. And then ideally, I’d go from there straight to the kind of walkthrough mentioned elsewhere, showing how to set up a subscription or a one-off charge using the new Stripe.js, APIs and webhooks with reference to the main concepts from that overview page. From that starting point, there is a frame of reference, and the more detailed explanatory pages and full API specs might make more sense to someone starting an integration essentially from scratch with little prior knowledge.