How to Write a Quickstart That Gets Someone to Working Code in Five Minutes

A quickstart has exactly one job: take a reader from nothing installed to one verified, working result, as fast as possible. Not a tour of the product, not the recommended production setup, not an explanation of the concepts. Four steps (install, authenticate, do one real thing, confirm it worked) and a single clearly marked exit to whatever they should read next. If your quickstart takes longer than about five minutes, it is a tutorial wearing the wrong title.

The discipline is entirely in what you leave out, and every instinct pushes the other way.

What a quickstart is, and what it is not

These are five different pages with five different failure modes. The quickstart fails when it tries to be the tutorial, which happens the moment somebody adds “while we’re here, let’s also configure…”. For the wider shape this sits in, see How to Structure a Documentation Site.

The five-minute rule, and how to hold yourself to it

Time it. Sit down with a clean machine, a stopwatch and your own quickstart, and stop when you have a working result. The number you get is the number your readers get, and it is almost always two to three times what the author assumed.

The four steps

Step 1: Install, in the reader’s own tooling

Offer the install command for each ecosystem you support, in tabs, with the language choice sticky across the page so nobody is reading npm at the top and Python at the bottom.

npm install @example/sdk
export EXAMPLE_API_KEY="sk_test_your_key_here"
npx example-sdk whoami

pip install example-sdk
export EXAMPLE_API_KEY="sk_test_your_key_here"
python -m example_sdk whoami

go get github.com/example/sdk@latest
export EXAMPLE_API_KEY="sk_test_your_key_here"
go run github.com/example/sdk/cmd/whoami@latest

Notice that each tab includes the credential export and a command that verifies the install in one breath. Three lines that can be pasted as a block are worth more than three separate snippets with prose between them, because the reader is going to paste them as a block regardless.

Step 2: Authenticate, with a key they can actually get

The single most common place a quickstart stalls is credentials. Link directly to the page where the key is generated (not to the dashboard, to the exact screen) and show what a valid key looks like so the reader can tell at a glance whether they copied the right thing.

Step 3: Do one real thing

One call that produces a result the reader can see. Not “hello world” printed to a terminal, but something that exists afterwards and can be looked at.

import { Example } from '@example/sdk';

const client = new Example({ apiKey: process.env.EXAMPLE_API_KEY });

const doc = await client.documents.create({
  title: 'Hello, docs',
  body: '# Hello, docs\n\nYour first document.',
});

console.log( doc.url );

Choose the operation that best represents what the product is for. If your product is a document API, create a document. If it is a queue, publish and consume one message. The reader is forming a first impression of what the thing does, and a contrived example teaches them the wrong shape.

Step 4: Confirm it worked

Show the expected output, exactly, and give the reader a second way to verify: a URL to open, a command that lists what they just created. Verification is what turns “it did not error” into “it works”, and it is the step most often left out.

Then stop. One line naming the next page, and end.

The four places quickstarts lose people

1. Undeclared prerequisites. The reader hits a missing dependency at step three and has to leave. List everything needed before step one, with versions.
2. Choices. “You can use either X or Y” makes the reader stop and decide. Pick one for them, and mention the alternative afterwards.
3. Placeholders that look like values. A key formatted as sk_test_your_key_here is obvious. One formatted as sk_test_4eC39Hq gets pasted verbatim and fails in a way that looks like your fault.
4. An unmarked ending. A quickstart that trails off into further reading leaves the reader unsure whether they finished. Say so: “That’s the whole quickstart. You now have X. Next, read Y.”

Every sentence in a quickstart is either moving the reader towards a working result or costing them time. There is no third category.

Test it on someone who has never seen the product

Watch a new colleague follow it, on their own machine, without helping. Do not answer questions; write them down. Every question they ask out loud is a missing sentence, and every pause longer than ten seconds is a step that needs splitting.

Do this once per major release. Quickstarts rot faster than any other page, because they depend on install commands, default settings and dashboard layouts that all move independently of the documentation.

Common questions