developer_quickstart_guide v1.0.0

name: "developer_quickstart_guide" description: "Write a developer quickstart that takes a reader from zero to one verified success: the minimal path, expected output at each step, fail branches for common errors, a cold run time budget, and a test pass by someone who did not write it. Use when drafting or fixing a quickstart, getting started page, or first-run guide for an API, SDK, CLI, or library."

Developer Quickstart Guide

Purpose

Get a new developer to one real, verified result with your product and nothing else in the way. A quickstart is a lesson in the Diataxis sense: the writer is responsible for the reader's success, the reader follows a single path without making design decisions, and every step produces a result the reader can see and check. Anything that teaches concepts, lists options, or covers a second use case belongs in another document, linked at the end.

This skill ships three working pieces: a fill-in quickstart template in templates/quickstart-template.md, a timed cold run checklist in references/cold-run-checklist.md, and a worked audit of a flawed quickstart in references/worked-audit.md. A checker script in scripts/audit_quickstart.py scores a draft against the rules below.

Workflow

1. Define the one success before writing a word. Write one sentence in this form: "After this guide, a developer with [stated prerequisites] will [do the core action] and see [the exact visible result]." Pick the core action that proves the product works: send one message, create one charge, run one query, print one result. If the sentence names two actions, cut one. The cut action becomes a Next Step link.

1. State the deal at the top. The opening block contains four things and no marketing copy: what the reader will build or do in one plain sentence, the time budget (see step 7), the prerequisites as a checklist with exact versions and accounts, and what success looks like. Google Workspace quickstarts use this shape consistently: one line on what will be created, an Objectives list, then Prerequisites before any setup step. Put a missing Docker install or API key in this block, never in step 4 where it breaks flow.

1. Lay out the minimal path. Order the steps as Install, Configure only what the first run needs, Do the core action, Verify. Sentry's internal quickstart guide makes Install always the first step so the reader acts within the first screen. Keep the path to 3 to 6 steps. Rules for each step:

• One action per step, titled with a verb.
• Every command in its own copy-paste block, with no $ prompt characters inside the block, so copy buttons and terminal paste work clean.
• Code examples complete and runnable as pasted, with only the credential or key left as a placeholder. The first example stays short, shows the default path only, and prints or returns something visible.
• No configuration options, alternate install methods, or architecture notes on the path. Move them behind a link or into a later guide.

1. Write the expected output under every step that produces output. Directly below the command or action, show what the reader should see: the exact success line, the shape of the response with real field names, or a trimmed sample with variable parts marked such as <your-id>. Diataxis calls this maintaining a narrative of the expected: at each step the reader is anxious about whether it worked, and the shown output is how they know. A step with no checkable output is a step the reader cannot confirm, so add a cheap check command (--version, a status call, a log line to look for) or merge the step into the next one.

1. Add a fail branch for each common error, inline at the step where it happens. For each step list the 1 to 3 failures a first-timer actually hits and write each as: the exact symptom the reader sees, the cause in one line, and the fix as a command or action. Cover at minimum, where they apply: wrong runtime version, command not found after install, missing or wrong credential (show the real error shape, for example a 401 response body), required port already in use, and running the command in the wrong directory. Do not collect these in a troubleshooting page at the bottom. A reader stuck at step 2 never reaches the bottom, and a symptom written at the step is findable by searching the error text.

1. End with a Verify step that proves the result outside the terminal. Verification runs the product's own surface: the message arrived, the record appears in the dashboard, the API returns the created object by ID, the page loads. Echoing "done" from the same script that did the work does not count. State the pass condition in one line: "You pass when you can see X in Y." Then add Next Steps: 2 to 4 links, each named for the job it does next (handle errors, add a second resource, deploy), not for the document type.

1. Set the time budget, then measure it in the cold run. Promise a budget at the top, and set it from a timed run, not from how fast the author can do it. A practical default budget is 10 minutes of reader work excluding account signup and large downloads, and the template records those exclusions explicitly. If the cold run exceeds the budget, either cut steps from the path or raise the stated budget to the measured time. Never ship a stated time no tester has hit.

1. Run the cold run test with a non-author. Follow references/cold-run-checklist.md. The tester did not write the guide, starts from a clean environment (fresh container, new virtual machine, or a machine where the product was never installed), uses only the guide plus the linked prerequisite pages, and works without help from the author. The author or a observer records per-step times, every pause over 30 seconds, every question, and every place the tester left the guide to search. Every pause, question, or departure is a defect in the guide, not in the tester.

1. Fix, re-run, and score. Fix the defects the cold run found, then have a second tester (or the same tester after a full reset) run the fixed version end to end. Score the final draft with the checker before publishing: python3 scripts/audit_quickstart.py path/to/quickstart.md The script checks for a prerequisites block, a stated time budget, expected output blocks, fail branches, a verify step, and next steps, and prints a per-check pass or fail list. A draft that fails a check gets fixed, not argued with.

1. Keep it true after shipping. Put code examples under test where the stack allows it: run the quickstart commands in CI on the stated prerequisite versions, or re-run the cold run checklist on every major release. A quickstart that no longer runs is worse than no quickstart, because the reader blames their own setup first.

Output Contract

A finished quickstart contains, in this order:

• Title and one sentence stating what the reader will do and for what product.
• Time budget line with its exclusions (signup, downloads) stated.
• Prerequisites checklist: exact runtime or tool versions, account or credential needed and where to get it, operating system limits if any.
• Numbered steps (3 to 6) covering install, minimal configure, core action, and verify. Each step has one action, copy-paste clean commands, and expected output wherever output exists.
• At least one fail branch per risky step, written as symptom, cause, fix, placed at that step.
• A Verify step with a one-line pass condition checked on the product's own surface.
• Next Steps with 2 to 4 job-named links.

Deliverables from this skill also include:

• The completed cold run record: tester identity as role (author or non-author), environment, per-step times, total time against budget, and the defect list with the fix applied for each defect.
• The audit script output for the final draft, with any failing check either fixed or explicitly waived with a reason.

Operating Rules

• One path only. Language tabs for SDKs are fine, alternate methods and optional features are not. A reader who must choose between options mid-guide is reading a how-to guide wearing a quickstart title.
• Do not mix document types. Explanation goes in an explanation page, full option lists go in reference. Diataxis separates tutorials, how-to guides, reference, and explanation because each serves a different reader need; welding them together is the common reason getting started pages feel heavy and still leave readers stuck.
• Never assume a step worked. If the guide does not show the reader how to tell, the guide has a hole at that step.
• Write error text verbatim where you quote it. Readers search for the exact string their terminal showed them. Paraphrased errors do not match search.
• Assume nothing unstated. Every tool, version, account, and file location the path needs appears in Prerequisites or at the step that creates it. The cold run exists to catch what the author stopped seeing.
• The author never signs off their own quickstart. The sign-off is a clean cold run by another person inside the stated budget with zero author help.
• Cut before you add. When a quickstart grows past one sitting, the fix is removing steps from the path and linking out, not better formatting of a long path.
• Keep secrets out. Examples use placeholder credentials with the exact format shown (prefix, length pattern) so a wrong paste is recognizable, and never a real key, token, or account ID.