Ryan Young - Is it (layer) cake: Thinking in content levels

Stripe’s documentation frustration isn’t coming from a lack of information—it’s coming from mismatched “content levels” that force users to make the wrong decisions at the wrong time. After reviewing customer feedback, Ryan Young found recurring complaints: too many options presented too early, information that users couldn’t apply in context, incorrect scope (either too broad or too narrow), unclear next steps, and missing links to the resources needed to finish the job. Even when guides contained the right facts, users still felt stuck because the docs didn’t help them reason through what to do next.

Young frames the problem through a user-job lens. Most people arrive at Stripe docs thinking they want to “accept payments,” but their real goals are more specific—creating subscriptions, adding buy buttons, building checkout sessions, or sending invoices. When the information architecture assumes a single path (or a single type of user), users experience choice overload and disorientation. Feedback also points to a growing mismatch between the original developer-first audience and newer users who either don’t want to write code immediately or don’t want to invest time in coding when payments are a side project. In those cases, “too technical” isn’t just about language—it’s about where the docs ask users to jump into implementation before they’ve understood the shape and scope of the integration.

To diagnose what was missing, Young compares docs to mall navigation. A mall directory helps orient visitors (“you are here” and where stores are), while signs help once they’re close to their destination. But granular store maps and high-level overviews alone don’t cover the middle distance where people need to make decisions—figuring out which path fits their situation before they start executing. That analogy leads to a three-layer “docs layer cake” framework.

At the top is the orientation layer: high-level overview pages that guide users to the right entry point for their use case, such as a payments landing page with direct links to detailed guides. The middle is the decision layer—new, intentionally designed content that helps users reason about options and understand the scope of their integration before writing code. Young argues this layer is absent in many doc systems, which tend to jump from overview to implementation.

Finally, the implementation layer contains the familiar low-level assets: integration guides, quick starts, and API reference material. These are most effective when users already know where they are and what they’re trying to build, so the docs can focus on execution, accuracy, and copy-pasteable steps. Young also notes that some implementation guidance can be embedded in the product experience (tooltips, in-context flows, immersive quick starts) to reduce context switching.

Stripe’s response includes dedicated “no code” documentation that follows the same layered pattern: overview landing pages, low-level UI-driven how-tos, and a decision-level doc that defines integration pieces, explains options in plain language, and ties them to common use cases. Early feedback suggests this middle layer reduces frustration for non-technical and time-constrained users and makes complex concepts like recurring payments easier to explain.

In the Q&A, Young describes how Stripe collects feedback through thumbs up/down prompts (with follow-up multiple-choice questions and free text), supplemented by user interviews and triangulated with page views and CSAT. When negative feedback appears, the team retraces user steps to determine whether the issue is documentation clarity, product gating, or a mismatch between what the UI exposes and what the docs describe. The overarching takeaway: docs work best when they match the user’s journey—orient, decide, then implement—rather than treating all readers as if they’re ready to execute immediately.