If you have shipped a developer product in the last ten years, you have stared at Stripe's Quickstart and wondered how a page that short could feel that generous. The answer is not the writing. It is the architecture underneath the writing.

This post tears down three of the most-studied getting-started guides on the public internet: Stripe's Quickstart, Twilio's SMS quickstart, and Supabase's "Getting started" sequence for creating a project and running your first queries. We picked these three because they were written by teams with different constraints, on different stacks, for different readers, and they still converge on the same seven structural moves. Name the pattern and you can grade your own page in ten minutes.

The thesis#

A great getting-started guide is not a good first page. It is a structural commitment that the next six pages will hold up. The best guides in the industry share a small set of features, and each feature is a design decision, not a writing flourish. Once you see the pattern you cannot unsee it. Once you build around it, the distance from signup to first successful call collapses, and the cost of every downstream support ticket drops with it.

Stripe: the thirty-second win#

Open Stripe's Quickstart and the first thing on the page is a runnable code sample, not a welcome message. The prose sits underneath the code, annotating it. That inversion is the single most-imitated, least-understood move in developer documentation. Most teams explain the system and then show the code. Stripe assumes you came for the code and will accept the concepts in the order the code presents them.

A few more moves compound that one.

The samples are pinned to a specific client library and, by convention, a specific API version. There is no "latest" ambiguity, which means a tutorial you followed in July still copy-pastes cleanly in January. The first request you make does not return "hello world." It returns a charge object in test mode, with an amount, a currency, and an id. You see the product do the thing the product is sold to do. The shape of the response is the shape of the response you will see in production.

The page is also honest about what happens next. Before you reach the end of the sample, the next step is named and linked: handle the webhook, or confirm the payment, or move to live keys. Stripe never leaves you hunting for the follow-on page in a sidebar. The sidebar is there, but the inline hand-off arrives first.

Taken together, the Stripe Quickstart is a demonstration that the shortest path to trust is a real object returned by a real call, with the next call already in view.

Twilio: the explicit scope#

Twilio's SMS quickstart opens with a promise you can evaluate in one sentence: by the end of this guide, your phone will buzz. That framing matters. It is not a learning journey, not a tour, not an overview. It is a procedure with a terminal condition.

Three structural moves carry the rest of the guide.

Prerequisites appear as a checklist above the code, not as a surprise in step four. You are told, up front, that you need a Twilio account, a verified phone number, and the relevant SDK installed. Nothing in the body of the guide asks you to stop, open a new tab, and come back with a credential you did not know you needed. This is a small thing that saves large amounts of time, and most guides get it wrong by splitting prerequisites across the page.

Code samples are offered in multiple languages, and the structure of each sample is the same across languages. The annotations line up. The variable names line up. A reader who switches from Node to Python mid-read does not lose their place, because the surrounding prose does not change shape. Language selection is a tab, not a fork in the narrative.

The guide also tells you, plainly, how to know you are done. The phone buzzes. The message appears. The API response contains a sid you can look up in the console. A completion criterion is a small courtesy to the reader and a large one to the support team, because a reader who cannot tell whether they succeeded will open a ticket that says "I think it worked?"

Twilio's guide is the cleanest example in the industry of scope as a design tool. One procedure, one success condition, one page.

Supabase: the continuity#

Supabase is the hardest of the three to imitate, because its getting-started is not a page. It is a short arc: create a project, define a table, run a query, wire it to a client. Each page ends where the next begins, and the state you built on page one is the state page two operates on. A reader who completes the arc has a working project, a schema, and a query that returns their own data.

Two structural moves do most of the work.

The guide leans on inline, executable editors in the places where context-switching would otherwise break the reader's flow. For the first several minutes, you are not toggling between the docs, your terminal, and your IDE. You are reading and running in the same surface. That compresses the feedback loop in a way that is hard to recover once a reader has alt-tabbed away and remembered they have Slack open.

Architecture is taught inside the action, not beside it. You learn that Supabase is Postgres with policies on top by writing a table and then writing a policy against it, not by reading a concepts page first. This is the riskiest of the three patterns. Done badly, it hides the model and produces users who cannot debug their own projects. Done well, it produces users who understand the model because they built against it, which is what Supabase is reaching for.

The continuity is the point. A single-page quickstart is a promise about the first five minutes. A multi-page arc is a promise about the first hour, and Supabase is one of the few teams that keeps it.

The seven-point pattern#

Stripe, Twilio, and Supabase are solving different problems with different surfaces. The moves they share are not stylistic. They are structural, and they appear together because each one depends on the others to work.

A runnable sample above the fold. Not a diagram, not a philosophy paragraph, not a welcome. The first thing on the page is code a reader can copy and run.
Pinned versions and explicit prerequisites. The sample names its library version. The page names the accounts, keys, and tools the reader must have before they start. Nothing is discovered halfway through.
A product-shaped first result. The first successful call returns an object that is recognizably the product, not a "hello world." A charge, a message sid, a row in a table.
A stated completion criterion. The reader is told, in plain language, what success looks like and how to verify it. A buzz, a 200, a visible row.
A named next step, inline. Before the current page ends, the follow-on page is linked in context, not only in the sidebar.
One path per page. Language tabs, environment toggles, and framework switches are presented as isolated tracks. The prose around them does not branch.
A short prose-to-code ratio. Code dominates the page. Prose is there to annotate, warn, or hand off, and every paragraph is doing one of those three jobs.

Most getting-started guides miss four of these, and the misses rhyme. The page opens with three paragraphs about the company's mission. The "Installation" section explains the package manager instead of installing anything. The first sample prints a string. The next step lives on a different tab. Prerequisites are introduced one at a time, each at the moment the reader trips over them. Language tabs change the surrounding prose, so switching from Python to Go loses the reader's place. None of these are writing problems. They are structural problems, which is why adding more words never fixes them.

A rubric you can run in ten minutes#

Open your own getting-started page in one tab and this list in another. Score one point per item. Be strict; partial credit is how bad guides stay bad.

Is a runnable code sample visible without scrolling past prose, headers, or marketing?
Is the sample pinned to a specific library version, and are all prerequisites listed in one block before the code?
Does the first successful call return an object or event that is recognizably your product, not a placeholder?
Does the page state, in one sentence, how the reader will know they succeeded?
Is the next step named and linked in the body of the page, before the end?
Does the page present one language or environment path at a time, with no branching in the prose?
Is the page mostly code, with prose that annotates, warns, or hands off, and nothing else?

Five or better, you have a working guide and a tuning problem. Four or below, the fix is mechanical, not creative. You do not need a new writer. You need to move the code above the prose, pin the version, swap the hello-world for a real object, state the success condition, link the next page inline, isolate the language tabs, and cut the paragraphs that are not doing one of the three prose jobs. In that order.

Why this is a structural problem, not a writing one#

The temptation, when a getting-started page is not converting, is to rewrite it. Rewriting rarely helps, because the failure is almost never the sentences. The failure is that the page is shaped wrong: the code is in the wrong place, the prerequisites are scattered, the first result is a toy, the next step is hidden, the tabs branch the narrative. You can polish every sentence on a page like that and the activation number will not move.

The three guides above are not longer than yours. They are shaped differently, and shape is copyable. We have yet to see a getting-started page that scores under four on the rubric and converts well, and we have yet to see one that scores six or seven and converts badly. The correlation is not subtle.

What we do with this at DevDocs#

When we audit a developer product's onboarding, the rubric above is the first pass. It takes ten minutes and it tells us, before we read a single sentence closely, which of the seven moves the team has already made and which they have not. The rewrite plan writes itself from there: move the sample up, pin the version, replace the hello-world with a product-shaped call, state the completion criterion, link the next step inline, isolate the language paths, and cut the prose that is not annotating, warning, or handing off.

The craft is not in inventing a new pattern. The craft is in noticing that a pattern exists, naming it, and applying it with the same rigor you apply to the code the page documents. Stripe, Twilio, and Supabase did the noticing for us. The rest is work.