developer-quickstart-guide

Pick one observable success moment, set a time budget for your product class, then write three to six steps each with a verb-led heading, one copy-pasteable command block, the expected output, and a one-line fail branch. Verify the page by cold-running it on a clean machine with a fresh account.

Baseline budgets are 5 minutes for a hosted API or CLI, 10 minutes for an SDK, database, deploy platform, or auth product, and 30-60 minutes for self-hosted infrastructure. If a cold run exceeds the budget, shrink the success moment rather than extending the budget.

Default to the plain docs page and move up one rung only when a measured cold run shows friction the words cannot fix, such as a toolchain install that dominates the budget. An embedded sandbox removes the most friction but costs the most to build and maintain, so delete it from the shortlist if no owner will keep it working.

Common causes are prerequisites discovered mid-run, commands that fail when pasted verbatim, missing expected output, and explanation prose before the first action. Cold-run the page on a clean environment, log every defect with elapsed time, and instrument step-level drop-off events to name the exact step that breaks the run.

Use a tutorial when the reader is new to the problem space and needs concepts taught through progressive exercises. A quickstart serves domain experts who know the problem and only need to see your product work once, so it deliberately teaches nothing general and follows a single happy path.

Run the page's command blocks verbatim in CI against the published package or public endpoint, asserting the documented outputs with normalized patterns for ids and timestamps. Provision a throwaway tenant per run, run on a schedule as well as on release, and fail the release when the run fails.