samber/developer-relations-skills包含需要注意的行为
SKILL DETAIL
developer-quickstart-guide
samber/developer-relations-skills/developer-quickstart-guide
Writes or audits a developer quickstart that carries a reader from zero to one verified success - minimal path, copy-paste commands, expected output at every step, fail branches, and a cold-run time budget. Use whenever the user mentions a quickstart, a getting-started page, a hello-world doc, "time to first success" or "time to first value", onboarding docs for an API, SDK, CLI or self-hosted tool, or complains nobody finishes their getting-started page - even if they only say "our setup is too hard". Do NOT use for a teaching tutorial (samber/developer-relations-skills@developer-tutorial) or a README rewrite (samber/developer-relations-skills@readme-optimization).
安装量 · 427查看来源
Installation
npx skills add https://github.com/samber/developer-relations-skills --skill developer-quickstart-guide
技能文件
SKILL.md
最近同步 · 2026年10月23日
evals/evals.json›
{
"skill_name": "developer-quickstart-guide",
"evals": [
{
"id": 1,
"prompt": "We're a small team at Reticule shipping a hosted geocoding API - you POST an address and get back coordinates plus a confidence score. Public launch is in about five weeks and I need the getting-started page written. I want it to have an embedded StackBlitz sandbox, because a competitor's sandbox is literally why I tried them. Success for us = the developer has made their first API call and understands how our auth model and rate-limit tiers work. Right now getting a key means emailing our sales inbox and someone provisions a sandbox tenant for you, usually next business day. Docs infra isn't anyone's job here - we're four backend engineers and a founder who writes the blog.",
"expected_output": "An interview-grounded quickstart plan: a restated observable success moment, a 5-minute budget, a plain-page container with the sandbox struck from the shortlist, an escalation of the access mechanism above the sales-gated tenant, the four-part step shape, and a cold-run verification plan.",
"files": [],
"expectations": [
"Rejects 'the developer has made their first API call' as the success moment because it names a step the reader performs rather than something the product visibly does.",
"Replaces it with an observable result, such as the response carrying coordinates for the address the reader just submitted.",
"Commits to a time budget of 5 minutes for this hosted-API quickstart.",
"Recommends a plain documentation page as the container instead of the embedded sandbox.",
"Identifies the embedded sandbox as the lowest-efficiency container: the most friction removed, but the highest build-and-upkeep effort.",
"Deletes the embedded sandbox from the shortlist entirely rather than ranking it last, because the team named no owner to keep it working.",
"Names the sales-inbox key provisioning as the dominant friction and asks for a higher access rung - no account at all, a temporary development key, or an instant self-serve key - before any signup step is written.",
"Presents the access mechanisms as a ranked ladder in which the sales-gated sandbox ranks last.",
"Keeps the auth-model and rate-limit-tier explanation out of the quickstart, routing it to explanation or reference documentation.",
"Specifies each step as a verb-led heading naming the whole outcome, exactly one copy-pasteable block, the expected output, and a one-line fail branch.",
"Delivers a cold-run verification plan naming the environment and who executes it, rather than a page with no verification attached."
]
},
{
"id": 2,
"prompt": "Our getting-started page for Halyard (a managed Postgres branching service) has been up for a year. Analytics say 62% of the people who load it never reach the 'create branch' call at the end. The page honestly looks fine to me and to the two engineers who wrote it - all three of us run through it without any trouble. Can you rewrite it so people actually finish? I'll paste the current page content if you need it but you can probably tell what's wrong from the structure: intro paragraph about branching, install CLI, auth, create project, create branch, next steps.",
"expected_output": "A cold-run-first audit: a defect table ordered by minutes lost with the rewritten page after it, plus the clean-environment protocol, a two-profile run, a friction log, and a 10-minute budget.",
"files": [],
"expectations": [
"Cold-runs the existing page before rewriting anything, and states that rewriting from reading alone is not acceptable.",
"Returns a defect table whose rows carry the step number, what the page says, what actually happened, and the elapsed time at that point.",
"Orders the defect table by minutes lost.",
"Leads with the defects and places the rewritten page after them, presenting the rewrite as the fix rather than the finding.",
"Requires the cold run to happen on a clean environment with a fresh account, no cached credentials and no pre-installed dependencies.",
"Starts the timer at page load, not at the first command.",
"Treats any command the runner had to adjust to make work as a defect, rather than silently fixing it.",
"Treats an output that differs from the documented output as a defect even when the command still succeeded.",
"Requires a second run by a reader profile new to the ecosystem, distinct from one fluent in it, because the authors' own runs under-catch assumed knowledge.",
"Keeps a friction log beside the defect table, tagging each entry green for delight, yellow for friction, red for blocking.",
"Commits to a 10-minute budget for this database/data-platform product class."
]
},
{
"id": 3,
"prompt": "Quick question. Tessera is our CLI that compiles design tokens into platform-specific files. Our getting-started page runs to 14 numbered steps: install Homebrew, install the CLI, create an account, verify your email, run `tessera login`, create a workspace, invite a teammate, install the VS Code extension, create a tokens file, configure a build target, run the build, inspect the output, set up the CI action, and read the theming overview. Is that too long? I don't have a week to spend on this.",
"expected_output": "An audit only: per-step time attribution, a cut list ranked by minutes saved, the CLI budget and step-count rule, the artefact-on-disk success moment, and a scope cut rather than a longer budget.",
"files": [],
"expectations": [
"Returns an audit only and does not emit a rewritten quickstart page.",
"Returns a step-by-step time attribution across the 14 listed steps.",
"Returns a cut list ranked by minutes saved.",
"Names 5 minutes as the baseline budget for a CLI quickstart.",
"States that a quickstart carries roughly three to six steps, and that 14 means the success moment is too large.",
"Defines the success moment as the compiled artefact on disk and requires the page to show its contents, for example an `ls` or `cat` of the generated file, not merely the build command's exit.",
"Cuts 'invite a teammate', 'install the VS Code extension', 'set up the CI action' and 'read the theming overview' as work the success moment does not need, naming where each one belongs instead.",
"Resolves the overrun by shrinking the success moment rather than raising the time budget.",
"Moves the surviving requirements (Homebrew, account, login) into a before-you-start block, each with a one-line check command, rather than leaving them as numbered steps."
]
},
{
"id": 4,
"prompt": "Grindstone is our hosted feature-flag API. The getting-started page is genuinely clean - we cold-ran it on a fresh laptop last month, it takes 6 minutes end to end, every command works, output matches. 71% of readers who start it reach the final step. But 30-day activation from docs signups has been flat at 3% for a year. Marketing wants to rewrite the page with a stronger hero section and an embedded video. What would you do?",
"expected_output": "A measurement deliverable, not an authoring one: success event and funnel definition, the drop-off questions to answer first, the KPI instrumentation order with day-7 return promoted, and a baseline-derived target.",
"files": [],
"expectations": [
"Treats this as a measurement and instrumentation problem rather than an authoring one, and does not produce a rewritten page.",
"Defines the success event and the funnel steps to instrument.",
"Lists the drop-off questions the data must answer before any rewrite is commissioned.",
"Instruments step-level drop-off first, because every other page metric falls out of the same events.",
"Ranks support tickets or issues quoting a specific quickstart step above median time-to-success and completion rate.",
"Notes that median page-load-to-success time and completion rate tie, because both read the same start-and-success event pair and neither localises a defect.",
"Promotes day-7 return of completers above the cheaper metrics, specifically because completion is healthy while activation is flat.",
"States that day-7 return requires docs and product to share an identity, decided before publishing.",
"Raises the possibility that the chosen success moment itself is the wrong one, since no cheaper metric can establish that.",
"Sets any KPI target from the page's own baseline measured over roughly four weeks, as a relative improvement, and refuses to import a benchmark number from an outside vendor's blog."
]
},
{
"id": 5,
"prompt": "Can you tidy up these two steps of our quickstart? Product is Quillpost, a transactional email API.\n\n## Installing the client\n\nRun `$ npm install` to pull in the client library.\n\n## Configuring your credentials\n\nCreate a client with your key:\n\n```\n1 const qp = new Quillpost(\"qp_live_9fT2xA\");\n2 // your key is in Settings > API\n```\n\n## Sending your first email\n\n```\nawait qp.send({ to: \"[email protected]\", subject: \"Hi\", body: \"Test\" });\n```\n\nThat's it! Now check out templates, webhooks, scheduling, batch sends, our Terraform provider, and the analytics dashboard.",
"expected_output": "A rewritten block set fixing every copy-paste defect: prompt and line numbers stripped, package named and pinned, an unmistakable test-scoped placeholder, full runnable file with imports, verb-led outcome headings, separate expected-output blocks, fail branches, and three next steps.",
"files": [],
"expectations": [
"Removes the `$` shell prompt from the install command.",
"Names the package explicitly instead of a bare `npm install`, and pins a version.",
"Removes the line numbers from the code block.",
"Replaces `qp_live_9fT2xA` with an unmistakable placeholder such as `<YOUR_API_KEY>`, and states that a plausible-looking fake value gets pasted verbatim.",
"Flags the `live` scope of the key specifically and recommends a test-scoped key, so a copy-paste mistake cannot send real email or cost money.",
"Moves the `// your key is in Settings > API` commentary out of the copy-pasteable block, placing it immediately before or after.",
"Replaces the 'Settings > API' wording with a direct one-click link to the credential page.",
"Gives the complete runnable file including its `import` statement, rather than the fragment shown.",
"Rewrites each heading as a verb-led statement of the whole outcome and removes the `-ing` form.",
"Adds an expected-output block to each step, in a separate block from the command so the output cannot be copied along with it.",
"Adds a one-line fail branch to each step, tied to its most likely error.",
"Cuts the closing list to at most three next steps."
]
},
{
"id": 6,
"prompt": "Northgate is our observability SDK. We officially support TypeScript, Python, Go, Java, Ruby and Rust. Product wants all six as tabs on the getting-started page in time for our user conference in nine weeks. The docs site runs on Docusaurus. Realistically we'll only run the TypeScript path ourselves - the other five we'll generate from the TypeScript version and have each SDK owner eyeball them before we ship. Can you set that up?",
"expected_output": "A refusal of eyeball-only verification, a reduction from six tabs toward two or three or separate pages, synchronized tab groups, the per-release cold-run cost, the branching-is-not-a-tab rule, and a 10-minute SDK budget.",
"files": [],
"expectations": [
"Refuses the eyeball-only verification and requires every tab to be cold-run independently.",
"States that each tab is its own quickstart sharing a layout, and that an unverified tab is worse than a missing one because the reader trusts it identically.",
"Flags six tabs as too many, naming two or three genuine first-class languages as the practical limit.",
"Reads the demand for six tabs as a signal the page is serving audiences that want different success moments, and offers separate per-language pages as the alternative.",
"Requires the tab groups on the page to be synchronized through a shared group identifier, so choosing a language once switches every remaining block and persists across visits.",
"Names the recurring cost of tabs as re-running every tab each release, not the one-time wiring.",
"Distinguishes parallel language variants from real conditional branching such as a proxy or firewall path, and routes real branching to a how-to guide rather than a tab.",
"Places language tabs in the middle of the container ranking and confirms the plain page remains the default.",
"Asks whether the page is a one-off launch asset or a compounding one, and ties the synchronized switcher and CI-run commands to the compounding answer.",
"Commits to a 10-minute baseline budget for this SDK/library quickstart.",
"Keeps the same success moment, step shape and verification across every language variant."
]
},
{
"id": 7,
"prompt": "Ferrous is our on-prem data-masking engine. Banks and insurers buy it. On my laptop the quickstart takes about 4 minutes: pull the image, run it, curl the health endpoint, mask a sample record. But our field engineers say new customers take two to four weeks to get through that same page, and the single most common support ticket is literally 'stuck at step 1'. Make the page faster.",
"expected_output": "A diagnosis that access, not code, is the bottleneck: an upfront provisioning block with named owners, air-gapped command variants, pinned image tags, resource prerequisites, the self-hosted budget, and an identical success moment.",
"files": [],
"expectations": [
"Identifies access provisioning rather than the code path as the bottleneck, stating that a 4-minute code path is wrapped in a multi-week access path the page never mentions.",
"Adds an upfront block naming exactly what must exist before step 1, such as tenant or licence, sandbox environment, role or permission, and allow-listed network or registry egress.",
"Names who inside the customer's own organisation provisions each of those items.",
"Rejects any 'contact your administrator' instruction that does not state exactly what to ask for.",
"Supplies an offline or air-gapped variant of every command that assumes internet access, including the image pull.",
"Keeps the success moment, step shape and verification identical to the self-serve version, changing only the access path.",
"Pins the container image tag rather than using a floating tag.",
"States resource requirements such as CPU, memory and disk as prerequisites, instead of letting the reader discover them mid-run.",
"Uses 30 to 60 minutes as the baseline budget for this self-hosted infrastructure quickstart, rather than carrying over the author's 4-minute laptop figure.",
"Treats the 'stuck at step 1' tickets as a signal localising an ambiguous instruction to a specific sentence, and uses them as an input to the fix.",
"Requires the cold run on a clean machine with a freshly provisioned tenant and no cached credentials, not the author's laptop."
]
},
{
"id": 8,
"prompt": "Cobalt is our columnar analytics database. The getting-started page runs about 2,600 words and roughly 70% of it is environment setup: pinning a Python version, installing a JDBC driver, getting a compatible Arrow build, installing our CLI. Then three steps to query a public taxi-trip dataset we host, and the payoff is a bar chart of trips per hour. Our data-eng team wants to move the whole page into a hosted notebook instead. Nobody has volunteered to maintain notebook infrastructure, though our platform team already runs a JupyterHub for internal analysts.",
"expected_output": "Setup split onto its own page linked from step 1, prerequisites with check commands, the notebook promoted on the strength of the existing JupyterHub, the demo dataset replaced by reader-inserted rows, and a 10-minute budget.",
"files": [],
"expectations": [
"Splits the environment setup onto its own page linked from step 1, rather than trimming it down inside the quickstart.",
"Justifies the split by noting readers need setup documentation long after they stop needing the quickstart.",
"Places every remaining prerequisite before step 1, each with a one-line check command and an install pointer.",
"States that any prerequisite discovered after step 1 during a cold run counts as a defect.",
"Recognises a chart, table or query result as the success moment that makes a notebook the fitting container.",
"Promotes the notebook above its default ranking specifically because the platform team already runs hosted notebook infrastructure, turning a standing job into near-free.",
"States that a notebook with no named owner would be deleted from the shortlist rather than ranked last.",
"Replaces the hosted public taxi dataset with rows the reader inserts during the quickstart and then queries, because a dataset the reader did not create weakens the proof.",
"Commits to a 10-minute baseline budget for this database/data-platform quickstart."
]
},
{
"id": 9,
"prompt": "Palisade is our API gateway SDK. The quickstart has broken silently twice this year - once when we renamed a config key in a minor release, once when an upstream dependency changed a default - and both times a customer found it before we did. I want this checked automatically. Separately: who should actually own writing these pages? Right now our one staff technical writer drafts all of them and she's about three weeks behind.",
"expected_output": "A CI regression job running the page's own blocks against the published artefact with throwaway tenants, scheduled runs and a release-blocking failure, plus a docs-as-code ownership model with the shipping engineer drafting.",
"files": [],
"expectations": [
"Runs the quickstart's own command blocks verbatim in CI, rather than a hand-maintained parallel script.",
"Runs them against the published artefact - the released package and the public endpoint - not the repository working copy, because readers never have the working copy.",
"Requires executable blocks to be annotated in the page source so an extractor knows which blocks to run.",
"Asserts the documented outputs, normalising volatile fragments such as ids, timestamps and durations with patterns rather than deleting the assertion.",
"Provisions a throwaway account or tenant per run so credential state never leaks between runs.",
"Runs on a schedule as well as on release, because upstream dependency and hosted-API changes break the page with no commit in the repository.",
"Fails the release on a failing run rather than filing a ticket.",
"Justifies the hard failure by stating that an outdated quickstart is worse than a missing one, because it spends the reader's trust before it spends their time.",
"Makes the shipping engineer the first-draft author for a quickstart tied to one SDK or feature, since at merge time they alone know the exact commands and output.",
"Keeps the writer in a review role and proposes a merge gate blocking pull requests without docs, so features get documented while fresh.",
"Asks the team to agree a review cadence and a final-authority rule, rather than asserting a standard one already exists."
]
},
{
"id": 10,
"prompt": "Write the quickstart for Vellum, our managed vector store. Our target users are data analysts at mid-size insurers - most of them have never worked with embeddings or chunking before, so the page needs to teach those concepts first. While you're in there, our repo README is a mess too, and the docs site nav has grown to about 40 items with no obvious order. Budget is one afternoon.",
"expected_output": "A scope check splitting the three requests: the concept-teaching audience routed to a getting-started guide or tutorial, the README and navigation routed to their own named skills, and the quickstart kept to one contrived happy path.",
"files": [],
"expectations": [
"Declines to cover all three requests in a single page and separates them into distinct pieces of work.",
"States that a quickstart's reader is a domain expert who knows the problem space and is new only to this product.",
"Routes the audience that must first learn embeddings and chunking to a getting-started guide or a teaching tutorial, instead of inlining the concepts.",
"Refuses to open the quickstart with concept or architecture prose, naming background before the first action as a defect.",
"Routes the README rewrite to the repository-landing-page skill rather than handling it inside the quickstart.",
"Routes the 40-item navigation problem to the documentation structure/information-architecture skill.",
"Names the specific sibling skills for those hand-offs rather than describing them vaguely.",
"Confirms that a quickstart deliberately teaches nothing general: one contrived happy path, no branching.",
"States that a quickstart drops detailed concept descriptions, walkthroughs of complex use cases, and explanations of why each step is performed.",
"Still puts prerequisites, versions and credential paths upfront, because 'domain expert' does not mean 'already set up'."
]
}
],
"trigger_queries": [
{ "query": "Write a quickstart for our new REST API", "should_trigger": true },
{ "query": "our getting started page is way too long and nobody finishes it", "should_trigger": true },
{ "query": "How long should time to first success be for a CLI tool?", "should_trigger": true },
{ "query": "we need a hello world doc for the Go SDK we're shipping next week", "should_trigger": true },
{ "query": "Nobody makes it past step 3 of our onboarding docs", "should_trigger": true },
{ "query": "audit our getting-started guide please", "should_trigger": true },
{ "query": "time to first value on our docs is terrible, help", "should_trigger": true },
{ "query": "Can you review the zero-to-first-call page for our payments API?", "should_trigger": true },
{ "query": "I want a page that gets a developer from signup to a working request in five minutes", "should_trigger": true },
{ "query": "honestly our setup is just too hard", "should_trigger": true },
{ "query": "Should our getting started page use an embedded sandbox or just a plain page?", "should_trigger": true },
{ "query": "developers keep telling us they can't get our thing running at all", "should_trigger": true },
{ "query": "write the getting started section for our self-hosted deployment", "should_trigger": true },
{ "query": "how many steps should a quickstart have", "should_trigger": true },
{ "query": "we want the first success to happen without creating an account, is that worth building?", "should_trigger": true },
{ "query": "draft the five minute intro page for our new database product", "should_trigger": true },
{ "query": "people install the SDK and then never make a single call", "should_trigger": true },
{ "query": "Review this onboarding doc and tell me what will break on a clean machine", "should_trigger": true },
{ "query": "what should we actually measure on our getting started page?", "should_trigger": true },
{ "query": "our quickstart only works on my laptop", "should_trigger": true },
{ "query": "I need to prove our API works in under ten minutes for a launch next Thursday", "should_trigger": true },
{ "query": "should we add language tabs to the first-run page?", "should_trigger": true },
{ "query": "write onboarding documentation for our CLI tool", "should_trigger": true },
{ "query": "we keep discovering prerequisites halfway through our setup instructions", "should_trigger": true },
{ "query": "help me cut our getting started guide down", "should_trigger": true },
{ "query": "the first page a developer lands on after signup - make it actually work", "should_trigger": true },
{ "query": "Our activation rate after docs signup is 4% and the page itself seems fine", "should_trigger": true },
{ "query": "what's a good first success moment for an auth product?", "should_trigger": true },
{ "query": "make our hello world actually copy-pasteable", "should_trigger": true },
{ "query": "enterprise customers take three weeks to run our five minute quickstart", "should_trigger": true },
{ "query": "our getting started instructions go stale every release, can we test them in CI", "should_trigger": true },
{ "query": "draft a first-run guide for a hosted vector search API", "should_trigger": true },
{ "query": "I want to rewrite the page that takes someone from nothing to a working integration", "should_trigger": true },
{ "query": "how do I know if my getting started doc is any good", "should_trigger": true },
{ "query": "write the quickstart", "should_trigger": true },
{ "query": "first-time developer experience on our docs is bad, where do I even start", "should_trigger": true },
{ "query": "our onboarding page just assumes you already have Docker and a Postgres running", "should_trigger": true },
{ "query": "put together the ten minute guide for our deploy platform", "should_trigger": true },
{ "query": "review our 'try it in 5 minutes' page", "should_trigger": true },
{ "query": "developers bounce off our docs before they ever run anything", "should_trigger": true },
{ "query": "should the quickstart include an explanation of our architecture?", "should_trigger": true },
{ "query": "give me a verification plan for the getting started steps", "should_trigger": true },
{ "query": "we want a try-it console instead of written steps, good idea?", "should_trigger": true },
{ "query": "write a zero to running guide for our open source agent runtime", "should_trigger": true },
{ "query": "our first-run doc has seven next-step links at the bottom", "should_trigger": true },
{ "query": "what's the fastest path we can document from install to visible result", "should_trigger": true },
{ "query": "Write a tutorial that teaches someone to build a chat app with our SDK", "should_trigger": false },
{ "query": "Our docs site is a mess, where should each page actually live?", "should_trigger": false },
{ "query": "Rewrite our repo README so people understand what the project is", "should_trigger": false },
{ "query": "Document every endpoint in our API reference", "should_trigger": false },
{ "query": "Turn our support tickets into troubleshooting and error-code pages", "should_trigger": false },
{ "query": "Make our docs readable by coding agents and add an llms.txt", "should_trigger": false },
{ "query": "Set a policy every code sample across our docs has to meet", "should_trigger": false },
{ "query": "Should we build a certification program for our platform?", "should_trigger": false },
{ "query": "Map our developer journey from discovery through advocacy", "should_trigger": false },
{ "query": "Write the release notes for v3.2", "should_trigger": false },
{ "query": "Write an upgrade guide from v2 to v3 covering the breaking changes", "should_trigger": false },
{ "query": "Outline a conference talk about our scheduler architecture", "should_trigger": false },
{ "query": "My live demo broke on stage last week, help me make it reliable", "should_trigger": false },
{ "query": "Plan a developer meetup program across four cities", "should_trigger": false },
{ "query": "Write a CFP submission for KubeCon", "should_trigger": false },
{ "query": "Improve how our docs rank in Google search results", "should_trigger": false },
{ "query": "What DevRel metrics should we report to the board?", "should_trigger": false },
{ "query": "How should we split our DevRel budget next year?", "should_trigger": false },
{ "query": "Set up a Discord community for our users", "should_trigger": false },
{ "query": "Write an engineering blog post about our new scheduler", "should_trigger": false },
{ "query": "Help me build in public and share weekly revenue numbers", "should_trigger": false },
{ "query": "Design a governance model for our open source project", "should_trigger": false },
{ "query": "Pick a license for our new open source project", "should_trigger": false },
{ "query": "Triage the 400 open issues in our repo", "should_trigger": false },
{ "query": "Write a contributor onboarding guide so new people can send their first PR", "should_trigger": false },
{ "query": "Plan the Product Hunt and Hacker News launch for our devtool", "should_trigger": false },
{ "query": "Script a three minute product video", "should_trigger": false },
{ "query": "Prep me for a podcast interview next week", "should_trigger": false },
{ "query": "Write a customer case study about how Acme uses our API", "should_trigger": false },
{ "query": "Set the pricing tiers for our developer plan", "should_trigger": false },
{ "query": "Optimize my GitHub profile page and pinned repos", "should_trigger": false },
{ "query": "Design an onboarding email sequence for people who just signed up", "should_trigger": false },
{ "query": "Write the first-run screens for our mobile app's onboarding flow", "should_trigger": false },
{ "query": "Create a 30-60-90 onboarding checklist for engineers joining the team", "should_trigger": false },
{ "query": "Write an onboarding plan for a new reseller partner", "should_trigger": false },
{ "query": "Which keywords should our developer docs be targeting?", "should_trigger": false },
{ "query": "How do we find and grow developer champions inside our accounts?", "should_trigger": false },
{ "query": "Write a go-to-market plan for our developer-first product", "should_trigger": false },
{ "query": "Audit the health of our open source community", "should_trigger": false },
{ "query": "Draft a moderation policy for our community forum", "should_trigger": false },
{ "query": "Should we sponsor this conference at the gold tier?", "should_trigger": false },
{ "query": "Segment our developer audience into usable groups", "should_trigger": false },
{ "query": "Write a press release for our Series A", "should_trigger": false },
{ "query": "Build our employer brand so we can hire more engineers", "should_trigger": false },
{ "query": "Compare our DevRel program against our two closest competitors", "should_trigger": false },
{ "query": "Plan our developer content calendar for Q3", "should_trigger": false }
]
}
references/delivery-mechanisms.md›
# Delivery mechanisms
A quickstart's content and its container are separate decisions. Pick the content first; then walk the ranked containers below from the top and stop at the first one that removes the friction actually breaking your budget.
## Contents
- Choosing a container
- Language and platform tabs
- Embedded browser sandboxes
- API try-it consoles
- Notebooks
- CLI scaffolding
- What every non-page container still owes you
## Choosing a container
Rows run best-ratio-first: friction removed per hour of building the container and holding it working.
| Container | Friction it removes | Build and upkeep | Reach for it when |
| ---------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Plain docs page | None beyond the words | Near-zero - it breaks only when the commands do | Default. Always, and especially when the reader's own machine is the point |
| CLI scaffold | Install and project-setup steps, outright | An hour to document; the generator is owned by product either way | "Start a new project" is the real onboarding path |
| Try-it console | The client setup between reader and first response | Near-zero when an OpenAPI spec is already published; a standing job to keep the spec current | The success moment is a response from a hosted API |
| Language tabs | Re-reading the path in the wrong language | An hour to wire, then every tab is a quickstart you must cold-run each release | Two or three genuine first-class languages, no more |
| Notebook | Install, and the gap between narrative and a chart | A week: its own hosting, execution and rendering story | The success moment is a chart, a table or a query result |
| Embedded sandbox | The whole toolchain install | A standing job: a third-party runtime becomes a dependency of your onboarding | Toolchain install is the single biggest time sink in the budget |
- value: embedded sandbox > CLI scaffold > notebook > try-it console > language tabs > plain page
- build and upkeep effort: embedded sandbox > notebook > language tabs > try-it console > CLI scaffold > plain page
- compliance cost: embedded sandbox > notebook > try-it console > language tabs == CLI scaffold == plain page
- efficiency: plain page > CLI scaffold > try-it console > language tabs > notebook > embedded sandbox
Compliance cost belongs on this menu because three containers execute the reader's code, and sometimes their credentials, on a third party's infrastructure. An enterprise reader's security review, and any data-residency commitment you have made, gate the sandbox and the hosted notebook runner before the reader ever loads them. Tabs, scaffolds and the page itself trigger no review and are reversible in a commit, which is why they tie.
The last three rows tie on compliance cost for the same reason and nothing else; they differ sharply on effort, so never read that tie as equivalence.
**Default: the plain page.** Move up exactly one rung when a measured cold run shows the friction that rung removes is what breaks the budget - not because the rung looks impressive in a launch.
That order starves the embedded sandbox: the container that removes the most friction loses every round on effort. Promote it anyway when the toolchain install alone exceeds the time budget, or when the reader cannot install anything on a locked-down machine.
Delete the sandbox and the notebook from the shortlist, rather than leaving them at the bottom, whenever the interview named no owner for the container or a security review the team will not clear. A container nobody maintains fails in front of the reader on their first visit.
This ranking is a default, not a law: it shifts with what the team already runs.
- An OpenAPI spec already published promotes the try-it console.
- A docs framework with a working tab group promotes tabs.
- An in-house sandbox the platform team already maintains for something else moves the sandbox from a standing job to near-free, and straight to the top.
No published selection framework was found for this decision; the ordering and the fit column follow from what each container structurally can and cannot do, and from what each one costs to keep alive. Say so if you present it as guidance.
## Language and platform tabs
A language switcher looks like branching but is not. It renders one path in parallel variants; the reader picks once, and nothing downstream forks on a variable.
- Implement it as tab components wrapping the blocks that diverge, at the exact point of divergence.
- Synchronize every tab group on the page through a shared group identifier, so choosing Python once switches all remaining blocks and persists across visits. Docs frameworks that support this (Docusaurus's `groupId` being the reference implementation) also keep groups with different identifiers independent.
- Real branching (for example, "if you're behind a proxy, do X, otherwise Y") is not a tab. That is a how-to guide's job.
- Every tab is its own quickstart sharing a layout. Cold-run each one. An unverified tab is worse than a missing one, because the reader trusts it identically.
- More than two or three tabs is a signal, not a feature: the page is trying to serve audiences that want different success moments. Consider separate pages.
## Embedded browser sandboxes
Useful when installing the toolchain is the single biggest time sink in the path.
- Browser-native runtimes (StackBlitz's WebContainers) boot a development environment inside the tab itself, client-side, with no server round-trip per action.
- Hosted sandbox VMs (CodeSandbox and its embeddable Sandpack component) suit examples that need a real backend process rather than pure client-side execution.
- Terminal-scenario platforms (Instruqt) sandbox a full CLI or infrastructure environment instead of a JS runtime, reaching the CLI, database and self-hosted infrastructure product classes a browser-native JS sandbox cannot.
- Shared tradeoff: the reader's environment is the vendor's, not theirs. A green run in a sandbox does not prove the page works on a real machine, so keep at least one real-machine pass in the cold-run protocol.
- Second tradeoff: the sandbox is now a dependency of your onboarding. Decide what the page does when it is down or blocked by the reader's network.
## API try-it consoles
- A console generated from an OpenAPI specification lets the reader call the live API from the docs page with no authoring cost beyond keeping the spec current.
- It shows exactly the operations in the spec, so it cannot demonstrate a multi-step flow or client-library ergonomics - retries, pagination helpers, typed responses. Those still need written steps.
- Use it beside the quickstart, not instead of it: the console proves the endpoint exists; the quickstart proves the reader can build with it.
## Notebooks
- A notebook interleaves narrative and executable cells in one linear document, which matches a quickstart's single happy path closely.
- Best fit when the success moment is a chart, a table or a query result rather than a terminal line.
- Cost: notebooks render poorly as static docs pages and need their own hosting and execution story. Zero-install hosted runners exist and are widely used for this, but treat the specific pairing as an implementation choice to verify, not a given.
## CLI scaffolding
A generator (`npm create <name>`, `cargo new`, and their equivalents) is a different delivery mechanism, not a shorter page. One command emits a project that already runs.
- It deletes the "install dependencies" and "create project structure" steps outright - the generator's prompts _are_ those steps - and it moves the success moment earlier.
- Copy-paste hazards mostly vanish: there is no command to mistype, only prompts to answer.
- Support both modes the way established generators do: a non-interactive flag for the experienced reader who wants zero friction, and a guided prompt path for the newcomer.
- It cannot replace the page. A skeleton is not the product's value; the reader still needs to be told what to do with the running scaffold to reach the real success moment.
- It only fits products where "start a new project" is the primary onboarding path. For a hosted API, an existing codebase, or a SaaS dashboard there is nothing to scaffold.
## What every non-page container still owes you
Whatever the container, the pass threshold does not change:
- Commands run verbatim.
- Output matches.
- No prerequisite appears mid-run.
- The budget holds.
- The reader never leaves to finish.
A sandbox that satisfies four of five has moved the friction, not removed it.
references/quickstart-template.md›
# Quickstart page skeleton
Fill this in and delete every section the product genuinely does not need. Nothing optional survives by default - each surviving line spends part of the time budget.
## Skeleton
```markdown
# <Verb the reader's outcome> in <N> minutes
<One sentence naming what will be working at the end. No product history, no architecture.>
## Before you start
- <Requirement 1>: check with `<command>` (<install pointer>)
- <Requirement 2>: check with `<command>`
- <Credential>: <how to get it in one click/step, with link>
## 1. <Install / connect>
`<single copy-pasteable block>`
You should see:
`<real output, trimmed but not edited>`
Not what you got? <one-line fail branch with link>
## 2. <Configure>
`<block using <YOUR_API_KEY> style placeholders>`
## 3. <Do the thing>
`<complete, runnable file or command; never a fragment>`
## 4. <See it work>
`<verification command>`
You should see:
`<the success moment, verbatim>`
## What just happened
<Two sentences at most, connecting the output to the product concept it proves.>
## Next steps
- <Most common second task>
- <Reference documentation>
- <Where to get help>
```
## Section rules
- **Title.** Name the reader's outcome and the time, not the product ("Send your first SMS in 5 minutes", not "Getting started with Messaging"). The time claim is a promise the cold run must honour.
- **Before you start.** Requirements only - things that must exist before step 1. Each gets a check command so the reader detects a mismatch here rather than at step 3. Credentials get a direct path, not "see the account settings documentation".
- **Steps.** Three to six. More than six means the success moment is too big; re-cut it. Number them so a support reply can say "step 3 failed". Each step covers:
- A verb heading.
- One block.
- Expected output.
- A fail branch.
- **Expected output.** Paste what the product really prints, trimmed of noise but never invented. A reader comparing their terminal to a fabricated output loses trust permanently.
- **What just happened.** The only place explanation is allowed, and only to bind the output to one concept the reader now needs. Skip it entirely if the output speaks for itself.
- **Next steps.** Three links maximum. More links means the reader chooses instead of continuing.
## Variants of the same page
When several ecosystems must be supported, keep one canonical path in this page and publish siblings with identical structure (`quickstart-python`, `quickstart-go`), each verified independently. Tabs inside one page work only when every tab is cold-run verified - an unverified tab is worse than a missing one, because the reader trusts it equally.
## What never belongs here
- Authentication theory, architecture diagrams, comparison tables.
- Configuration matrices and every flag a command accepts.
- Error catalogues beyond the one-line fail branches.
- Production hardening, scaling, or security guidance.
- Feature tours of anything the success moment does not need.
Each of these has its own home (explanation docs, reference, troubleshooting pages, how-to guides). Linking to them costs one line; inlining them costs the reader's remaining attention.
references/verification-protocol.md›
# Verification protocol
The author's machine always lies: it has the credentials, the runtime, the cached package and the tribal knowledge the page forgot to state. Verification exists to remove that advantage.
## Cold-run protocol
1. **Build a clean environment**: fresh container or VM, no global toolchains beyond the OS default, no cached package registries, no dotfiles.
2. **Create a fresh account** for the product (or a fresh tenant/project), with no prior configuration.
3. **Start a timer** at the moment the page loads, not at the first command.
4. **Execute every block verbatim.** Paste, run, record. Never fix a command silently - a command you had to adjust is a defect.
5. **Compare every output** to the documented output. Different is a defect, even when the run still succeeds.
6. **Log each defect** with its step number, what the page says, what actually happened, and the elapsed time at that point.
7. **Stop the timer** at the documented success moment.
8. **Repeat with a second reader profile**: someone fluent in the ecosystem and someone new to it. Their blockers differ, and only the second one finds the assumed knowledge.
An author's own cold run still under-catches: Tom Johnson's API documentation course reports a SendGrid getting-started tutorial that only 1 of 20 workshop participants completed successfully once tested against real readers live. A page that reads as finished to its author can still fail almost everyone who did not write it, which is the exact gap the second reader profile exists to close.
Record the run as a table so the same page can be re-measured after a fix:
| Step | Elapsed | Command ran verbatim | Output matched | Defect |
| ------- | ------- | -------------------- | -------------- | ----------------------- |
| Prereqs | 0:40 | yes | n/a | Node version not stated |
| 1 | 1:25 | no | no | package name missing |
## Pass threshold
The five ship criteria live in `SKILL.md` § Pass threshold - they are stated once so the two files cannot drift. Apply them here on the clean environment, for both reader profiles.
Failing the time budget means cutting the success moment, not raising the budget. Failing any other criterion means fixing the page and rerunning from step 1 of this protocol - a partial rerun misses defects the fix introduced.
## Friction log
While cold-running, keep a friction log alongside the defect table. This is the practice Aja Hammerly documented from Google's DevRel team, where new hires write one in their first weeks precisely because they lack the inside knowledge that lets veterans route around rough spots.
Frame it around the single scenario the quickstart serves. Log one line per moment of hesitation, confusion or surprise:
- The search term used.
- The link clicked.
- The command pasted.
- The reaction.
Tag each entry with Hammerly's stoplight convention:
- Green for delight.
- Yellow for friction.
- Red for blocking.
Hesitations are not defects yet. As this skill's own rule of thumb (not Hammerly's) - treat three hesitations in the same step as a sign the step is doing two things and should be split. The log's value is only realised when it reaches the people who can act on it: it covers docs and discoverability gaps, not just bugs.
## CI regression job
A page verified once decays as the product ships. Automate the run so drift fails loudly:
- Extract the quickstart's command blocks (annotate them in source so the extractor knows which blocks are executable).
- Run them in a clean container against the **published** artefact (the released package, the public endpoint) - not the repository working copy, since readers never have the working copy.
- Assert the documented outputs, normalizing volatile fragments (ids, timestamps, durations) with patterns rather than deleting the assertion.
- Provision a throwaway account/tenant per run so credential state never leaks between runs.
- Run on a schedule as well as on release: upstream dependencies and hosted-API changes break the page without any commit in your repository.
- On failure, fail the release rather than filing a ticket - an outdated quickstart is worse than a missing one, because it consumes the reader's trust before it consumes their time.
## Measurement instrumentation
Instrument the page so the funnel is observable without another manual run:
- Fire a distinct event at page load, at each step's copy-button click, and at the documented success action.
- Compute the median page-load-to-success time per week; it is the honest version of the number in the title.
- Break down drop-off per step, and treat the largest single drop as the next work item.
- Track issues and support tickets quoting a step number; each one names an ambiguous instruction.
- Compare completers' day-7 return against non-completers to confirm first success actually mattered.
When analytics are unavailable, run the cold-run protocol quarterly and after every major release; it produces the timing number, just less often.
references/worked-examples.md›
# Worked examples
Two versions of the same quickstart for an imaginary hosted API (`Pigeon`, a transactional messaging API). The product is invented so the pair can carry every defect at once; every defect in it is real and documented, but do not cite Pigeon as evidence of anything.
For a real published page to read alongside this, the Good Docs Project points at Jekyll's docs as a quickstart done well - notably, its setup information sits in a separate document linked from the first step rather than inside the quickstart.
Read the negative example first - the mistakes in it are the ones that survive review most often because each one looks helpful in isolation.
## Table of Contents
- [Negative example](#negative-example)
- [Installation](#installation)
- [Configuration](#configuration)
- [Sending](#sending)
- [Positive example](#positive-example)
- [Before you start](#before-you-start)
- [1. Install the client](#1-install-the-client)
- [2. Send a message](#2-send-a-message)
- [3. Confirm delivery](#3-confirm-delivery)
- [What just happened](#what-just-happened)
- [Next steps](#next-steps)
- [Applying this to other product classes](#applying-this-to-other-product-classes)
## Negative example
```markdown
# Getting started with Pigeon
Welcome to Pigeon! Pigeon is a modern messaging platform built on an
event-driven architecture. Before we begin, it helps to understand how
delivery guarantees work. Pigeon uses at-least-once delivery with
idempotency keys, which means…
[four more paragraphs]
## Installation
Run `npm install` to install dependencies.
## Configuration
Create a client with your API key. You can find your API key in the
account settings section of the dashboard.
const pigeon = new Pigeon("sk_live_4eC39H");
## Sending
Now send a message. Note that you need a verified sender identity first;
see the sender verification guide.
await pigeon.messages.send({ to: "+15551234567", body: "Hi" });
That's it! Explore the API reference to learn about scheduling, templates,
webhooks, batching, analytics, and our Terraform provider.
```
### Why each part fails
| Line | Defect | Cost |
| --------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------- |
| Delivery-guarantee preamble | Explanation before action | Reader spends the budget reading, not running |
| `npm install` with no package name | Assumed environment | Command fails verbatim; reader must guess |
| "find your API key in account settings" | Credential path not linked | Reader leaves the page and often does not return |
| `sk_live_4eC39H` | Plausible fake value, and a live-mode key | Pasted verbatim; fails with an auth error the page never mentions |
| Sender verification named at step 3 | Prerequisite discovered mid-run | Run stops; the real blocker is a separate multi-hour process |
| No expected output anywhere | Nothing observable | Reader cannot tell success from silent failure |
| Seven next steps | Choice overload | Reader browses instead of continuing |
## Positive example
```markdown
# Send your first Pigeon message in 5 minutes
You will send a test message from your terminal and see its delivery
status change to `delivered`.
## Before you start
- Node.js 18 or later: check with `node --version` (https://nodejs.org)
- A Pigeon test API key: [create one](https://example.com/keys) (no card required)
Test keys start with `sk_test_` and send to the sandbox only, so nothing
reaches a real phone.
## 1. Install the client
npm install @pigeon/client@3
## 2. Send a message
Create `send.js`:
import { Pigeon } from "@pigeon/client";
const pigeon = new Pigeon("<YOUR_TEST_API_KEY>");
const message = await pigeon.messages.send({
to: "+15005550006", // sandbox number, always accepts
body: "Hello from Pigeon",
});
console.log(message.id, message.status);
Run it:
node send.js
You should see:
msg_01HQ4B9K queued
`401 Unauthorized`? The key was not copied whole; it ends with a
checksum segment. Copy it again from the keys page.
## 3. Confirm delivery
npx pigeon messages get msg_01HQ4B9K
You should see:
status: delivered
delivered_at: 2026-08-26T09:14:22Z
Still `queued` after 30 seconds? The sandbox delivers within 5 seconds;
a longer wait means the message was sent to a non-sandbox number.
## What just happened
You created a message and Pigeon delivered it asynchronously: the send
call returns immediately with a `queued` status, and delivery status
arrives later.
## Next steps
- [Receive delivery webhooks](…)
- [API reference](…)
- [Community Discord](…)
```
### What the rewrite changed
1. Title promises an outcome and a time; the cold run enforces both.
2. Every prerequisite appears before step 1 with a check command and a one-click credential link.
3. The sandbox number removes the sender-verification prerequisite entirely - the strongest fix available is deleting a requirement, not documenting it.
4. Placeholder is unmistakable; the key shown is test-scoped, so a copy-paste mistake cannot cost money.
5. Every step shows real output and one fail branch tied to the most common error.
6. The asynchronous-delivery concept is explained only after the reader has seen it happen, in two sentences.
7. Three next steps, one per intent: build further, look things up, ask a human.
## Applying this to other product classes
- **CLI**: the success moment is the artefact on disk; show `ls`/`cat` output, not just the command's exit.
- **Self-hosted**: the success moment is a health endpoint answering; give one container command with pinned tags, and state resource requirements as prerequisites.
- **Data platform**: insert the rows in the quickstart itself, then query them - a demo dataset the reader did not create weakens the proof.
SKILL.md›
---
name: developer-quickstart-guide
description: Writes or audits a developer quickstart that carries a reader from zero to one verified success - minimal path, copy-paste commands, expected output at every step, fail branches, and a cold-run time budget. Use whenever the user mentions a quickstart, a getting-started page, a hello-world doc, "time to first success" or "time to first value", onboarding docs for an API, SDK, CLI or self-hosted tool, or complains nobody finishes their getting-started page - even if they only say "our setup is too hard". Do NOT use for a teaching tutorial (samber/developer-relations-skills@developer-tutorial) or a README rewrite (samber/developer-relations-skills@readme-optimization).
license: MIT
metadata:
author: Samuel Berthe
version: "1.0.1"
---
# Developer Quickstart Guide
You are a developer-documentation specialist. Your artefact is the quickstart page: it carries a reader to a single, visible, verified success, fast enough that they never consider closing the tab.
A quickstart is not a tutorial. It deliberately teaches nothing general: one contrived happy path, zero branching. The reader earns proof that the product works before spending real effort on it.
## Who the reader is
Sarah Maddox's definition (ffeathers, 2018), adopted by the Good Docs Project's quickstart template: "A quickstart guide is for domain experts" who "know the problem space and know exactly what they need to do." They are new to _your product_, not to the problem it solves.
That audience is what makes every cut safe. Maddox again: a quickstart drops:
- "detailed descriptions of the concepts"
- "detailed walkthroughs of complex use cases"
- "explanations of why they're performing each step"
A reader who needs those explanations is on the wrong page; route them via the scope check below.
Domain expert does not mean "already set up": prerequisites, versions and credential paths still go upfront.
## Scope check
Confirm the task is really a quickstart before starting. Route elsewhere when:
- The reader is new to the _problem space_ and needs concepts explained → getting-started guide or teaching tutorial.
- The reader needs to _learn_ through progressive exercises → teaching tutorial skill.
- The artefact is a repository landing page (badges, positioning, project structure) → README skill.
- The problem is _where content lives_ across a docs site → docs information-architecture skill.
- The problem is endpoint-by-endpoint completeness of API docs → API reference skill.
- The consumer is a coding agent rather than a human → agent-documentation skill.
Exact skill identifiers are in the References section.
## Interview
Ask these one at a time, multiple-choice whenever you can offer options. Stop as soon as you can define the success moment and the time budget; do not run the whole list mechanically.
**Memory: Store a few info about the current task or project context. When memory lives in a file, use `devrel-context.md`; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.**
1. What is the product class: hosted API, SDK/library, CLI, database/data platform, hosting/deploy platform, auth/identity, or self-hosted infrastructure?
2. What single thing should the reader see working at the end? Offer 2-3 candidate success moments and ask them to pick.
3. Does your reader already know this problem space, or are they meeting the category for the first time? A first-timer needs a getting-started guide; route per the scope check.
4. Who arrives on this page: an individual developer evaluating self-serve, a teammate onboarding onto an internal tool, or an enterprise evaluator on a gated/on-prem trial?
5. How does the reader get credentials: instant self-serve key, free tier with signup, sales-gated sandbox, or local-only (no account)?
6. Which single environment does the happy path use (language, package manager, OS)? Which other environments must at least be linked?
7. Is there an existing quickstart to audit, or is this greenfield?
8. Can you run the steps yourself on a clean machine, or do you need a verification plan someone else executes?
9. Do you have analytics on the current page (completion, drop-off, time to success), or is measurement part of the work?
10. What date must the page be live by? A hard date forces the plain docs page and defers every metric past step-level drop-off.
11. One-off win (a launch needs a page next week) or compounding asset (every new reader hits this page for two years)? Compounding promotes CI-run commands, a synchronized tab switcher and the day-7 join; one-off deletes all three.
12. What is the authoring ceiling in hours, and who keeps the container working every release? No named owner rules out an embedded sandbox and a notebook.
The container and KPI orders below are defaults, not laws. Re-rank them against these answers and against what the team already owns:
- A docs framework with a working tab switcher.
- An OpenAPI spec already published.
- An analytics pipeline already wired.
Each makes one option near-free and promotes it past the default order.
## Workflow
1. **Set the mode.**
- Greenfield: go to step 2.
- Audit: cold-run the existing page first (per step 10) and collect real defects before changing a word; never rewrite from reading alone.
2. **Pick the success moment.** It is the product visibly doing something for the reader, not a step the reader performs. Scope it to the product's primary feature and the quickest end-to-end path through it.
```
Bad: "Made an API call"
Good: "The response contains the record you just created"
```
3. **Set the time budget** (table below), then treat it as a hard constraint every later decision competes for.
4. **Delete prerequisites before documenting them.**
- The Good Docs Project's rule: "remove the burden of setup requirements as much as possible through sandbox accounts".
- The strongest form deletes the account itself. Temporary development keys or an anonymous dev deployment let the first run happen with no signup at all; this is the pattern most-installed vendor onboarding tools ship.
- Ask what it would take to make signup optional before you write a signup step.
Rank the access mechanisms by minutes deleted from the reader's path per week of product engineering, and ask for the highest rung the team can actually ship:
`no account at all > temporary dev key > instant self-serve key > free tier behind signup > sales-gated sandbox`
No account and a temporary key buy the same minutes; the temporary key ranks lower only because it needs issuing and expiry logic the anonymous path never writes.
5. **List what survives, upfront.**
- Every remaining requirement goes before step 1, each with a one-line check command (`node --version`) and an install pointer.
- Anything discovered mid-run is a defect.
- Where environment setup is large and durable, give it its own page linked from step 1, per the Good Docs API-quickstart rule.
Readers need setup docs long after they stop needing the quickstart.
6. **Choose one path, then one container.**
- One language, one package manager, one platform, one auth method.
- Alternatives go behind links or a synchronized language switcher, never as an inline choice the reader must reason about.
Rank containers by friction removed per hour of building and holding them:
`plain docs page > CLI scaffold > try-it console > language tabs > notebook > embedded sandbox`
**Default: the plain page.** Move up one rung only when the container removes friction the words cannot address: a toolchain install that dominates the budget, or a success moment that is a chart rather than a terminal line. See [./references/delivery-mechanisms.md](./references/delivery-mechanisms.md) for the per-container trade-off, the axes where they disagree, and what a non-page container still owes you.
7. **Write each step with four parts**, per the Good Docs Project's heading and step rules:
- A verb-led heading stating the whole outcome ("Connect to the VM instance", not "Connect", and never the _-ing_ form).
- Exactly one copy-pasteable block.
- The expected output.
- A one-line fail branch.
One action per step. Orient the reader first when a step needs a specific file or screen open.
8. **Land the success.** State the success moment explicitly ("you should now see the record you created"), then give at most three next steps:
- The most common second task.
- The reference.
- Where to get help.
9. **Run a humanizer pass** on the prose (never on code blocks) with your preferred humanizer skill, so the page reads like an engineer wrote it rather than a model.
10. **Verify by cold run** against the pass threshold below. Fix and rerun until it passes.
11. **Instrument and record.** Define the success event and the funnel (KPIs below). If your environment has persistent memory, store the chosen success moment, time budget, supported path, and rejected scope so later docs work stays consistent.
## Time budget
The Good Docs Project gives the only sourced outer bound: "a use case that your user can complete within 1 - 2 hours with a preference for a shorter time". No measured industry dataset backs anything tighter for developer quickstarts specifically, but a related, differently-scoped benchmark exists in general product onboarding research: a time-to-first-value of around 8 minutes is considered acceptable on web. That figure is not developer-tool-specific and should never replace the per-product-class budgets below, but it is a labeled adjacent data point for calibrating how aggressive the sub-10-minute end of the table should be.
The per-class budgets below are this skill's own baseline, not an industry benchmark. Treat them as the default to beat, and replace them the moment the product's real analytics say otherwise.
| Product class | Success moment | Baseline budget |
| -------------------------- | ---------------------------------------------- | --------------- |
| Hosted API | Response carries meaningful data | 5 min |
| SDK / library | Library performs the expected function locally | 10 min |
| CLI | Command produces the promised artefact | 5 min |
| Database / data platform | Query returns rows the reader inserted | 10 min |
| Hosting / deploy platform | App reachable at a live URL | 10 min |
| Auth | A user logs in successfully | 10 min |
| Self-hosted infrastructure | Service healthy and answering | 30-60 min |
## Invocation examples
Typical requests and what you produce for each:
- _"Rewrite our getting-started page, nobody finishes it."_ → Cold-run the current page, then return a defect table (step, what the page says, what happened, elapsed) followed by the rewritten page. Lead with the defects; the rewrite is the fix, not the finding.
- _"We're launching a Go SDK next week, write the quickstart."_ → Run the interview, propose 2-3 candidate success moments, then produce the page plus a cold-run verification plan someone on the team executes.
- _"Is our quickstart too long?"_ → Audit only. Return the step-by-step time attribution and a cut list ranked by minutes saved. Do not rewrite unless asked.
- _"Our quickstart works but activation is flat."_ → This is measurement, not authoring. Return the event/funnel definition and the drop-off questions the data must answer before any rewrite.
Expected output shape for a full build or rewrite:
```
1. Success moment + time budget (one line each, stated as commitments)
2. Defect table - audits only, ordered by minutes lost
3. The quickstart page - filled from references/quickstart-template.md
4. Cut list - what was removed and where it now lives
5. Verification plan - cold-run steps, environment, who runs it
6. Instrumentation - success event, funnel steps, KPI targets
```
Do not emit a rewritten page for an audit-only request, and never emit a page without sections 1 and 5; an unverified page with no stated budget is a draft, not a deliverable.
## Copy-paste rules
- Show commands and output in separate blocks so output never gets copied with the command.
- Strip shell prompts (`$`), line numbers, and interleaved commentary from command blocks.
- Make placeholders unmistakable (`<YOUR_API_KEY>`), never a plausible-looking fake value a reader pastes verbatim.
- Give the full file content when a file must be created, not a fragment the reader must place correctly. Include every required `import`/`using` statement.
- Comment the code sample immediately before or after it, not inside the command block.
- Pin versions in install commands when a floating version can break the path.
A compact negative/positive pair, since this is the rule most often broken in review:
```
Bad: Run `npm install` to install dependencies.
Good: npm install @acme/client@3
```
The bad line looks complete and fails when run verbatim: no package name, and an assumed package manager the page never stated. See [./references/worked-examples.md](./references/worked-examples.md) for the full page-length pair, which exercises the rest of this list.
## Pass threshold
Run the quickstart on a clean environment with a fresh account, no cached credentials, no pre-installed dependencies. It ships only when all five hold:
1. Every command succeeds exactly as written: no undocumented edits.
2. Every step's real output matches the documented output.
3. Zero prerequisites are discovered after step 1.
4. Measured elapsed time is within the budget you committed to.
5. A reader unfamiliar with the product reaches the success moment without leaving the page.
When the time budget fails, shrink the success moment; never extend the budget.
These five are this skill's own gate, not a published standard; each one maps to a defect a cold run can observe. The principle behind them is sourced: Manny Silva's docs-as-tests position that "documentation shouldn't just inform; it should also verify", and Write the Docs' Current principle, "consider incorrect documentation to be worse than missing documentation". See [./references/verification-protocol.md](./references/verification-protocol.md) for the full cold-run protocol.
## Friction log
While cold-running, keep a friction log beside the defect table. This is Aja Hammerly's Google DevRel practice: record every hesitation, confusion and surprise as it happens, tagged with her stoplight convention (green delight, yellow friction, red blocking).
Hesitations are not defects yet. One rule of thumb this skill adds (it is not Hammerly's): three hesitations in one step mean the step is doing two things; split it.
## KPIs
Instrument in this order; it is value per hour of wiring, not the order the metrics get reported in:
- **Step-level drop-off**: an event per step, an hour of wiring, and it names the step that breaks the run. Every other page metric falls out of the same events.
- **Support tickets or issues quoting a quickstart step**: near-zero to collect, a standing job to read, and each one localises a wrong or ambiguous instruction to a sentence.
- **Median time from page load to the success event**: free once the step events exist; it is the real time-to-first-success, and the only check on the budget you committed to.
- **Completion rate** (readers reaching the success event / readers starting): free once the step events exist; it says the page holds attention and nothing more.
- **Day-7 return of completers**: a standing job; docs and product must share an identity, decided before publishing. The only metric that says first success led anywhere.
Median time and completion rate tie on both axes, because they are two readings of the same start-and-success event pair: neither can be bought separately, and neither localises a defect. That order starves the day-7 return, the highest-value metric here and the most expensive. Promote it above everything when completion is healthy and activation is flat; no cheaper metric can tell you whether the success moment was the wrong one.
Set the target from the page's own baseline: measure four weeks as the default period, then commit to a relative improvement; never import a number from a vendor blog.
Guard against regression by running the quickstart's commands verbatim in CI against the published package and asserting the documented output; docs that only inform go stale silently, but docs that also verify fail loudly when the product drifts.
## Ownership
Put the quickstart in the same repository and pull-request workflow as the product, per Write the Docs' docs-as-code model:
- "developers will often write a first draft of documentation"
- a writer reviews it
- a merge gate blocking PRs without docs "incentivizes developers to write about features while they are fresh"
For a quickstart tied to one SDK or feature, make the shipping engineer the first-draft author; at merge time they alone know the exact commands and output.
Agree on a review cadence and final-authority rule with the team instead of assuming a standard exists.
## Failure modes
| Symptom | Fix |
| --------------------------------------------------------- | --------------------------------------------------------------------- |
| Page opens with background or architecture prose | Cut to the first action; move concepts to explanation docs |
| Prerequisite appears at step 3 | Move it to the prerequisites block with a check command |
| Reader must pick between three package managers | Pick one; link the others or use a synchronized switcher |
| Step has no expected output | Add observable output, or merge the step into the next one |
| Step heading is a bare verb ("Connect") or an _-ing_ form | Rewrite as a complete outcome (the _-ing_ form also translates badly) |
| Error output shown with no fix path | Add a one-line fail branch per documented error |
| Environment setup swells the page | Split it into its own page, linked from step 1 |
| Quickstart still works only on the author's machine | Cold run per the pass threshold; automate it in CI |
| Page grew past the budget over time | Re-cut scope to one success moment; split the rest into how-to guides (samber/developer-relations-skills@developer-how-to-guide) |
| Named vendor tools listed as required tooling | Describe the capability, not the vendor; the page outlives the tool |
| Language tabs added, only one tab ever verified | Cold-run every tab; each is its own quickstart sharing a layout |
## Reader-type split
The artefact is identical for every reader type:
- Same success moment.
- Same step shape.
- Same verification.
What changes is access.
**Individual / self-serve reader.**
- Optimize for zero-account or instant-key access.
- Cover the whole path with a free tier.
- No billing prompt before success.
Watch for the first example silently requiring a paid feature.
**Enterprise / gated reader.** The classic defect: a 5-minute code path wrapped in a 3-day access path the page never mentions. Access is the bottleneck, not the code.
- State upfront what must exist (tenant, sandbox, role, allow-listed network) and who provisions it.
- Give an offline/on-prem variant of every command that assumes internet.
- Never write "contact your administrator" without saying what to ask for.
## References
- samber/developer-relations-skills@developer-docs-structure-audit for where content belongs across a docs site.
- samber/developer-relations-skills@docs-code-sample-standards for sample policy and per-language parity.
- samber/developer-relations-skills@coding-agent-docs-optimization when the consumer is an agent, not a human.
- samber/developer-relations-skills@developer-troubleshooting-docs for the error pages the fail branches link to.
- samber/developer-relations-skills@developer-journey-map for the stage this guide's first-success rate feeds.
- samber/developer-relations-skills@developer-how-to-guide for the task pages a reader needs once the first success lands.
Named sources behind this skill:
- Sarah Maddox, "What is a quickstart to you?" (ffeathers, 2018): the audience definition.
- The Good Docs Project, quickstart and API-quickstart template guides: step, sample and setup rules, and the 1-2 hour bound.
- Diátaxis (Daniele Procida): the tutorial/how-to split.
- Write the Docs: documentation principles and the docs-as-code guide.
- Manny Silva: docs as tests.
- Aja Hammerly: the friction log.