# 10-minute Getting Started tutorial > Depth-first rabbithole dossier for 10-minute Getting Started tutorial; source-anchored research pack. Parent: [API Documentation Craft](https://llms-explorer.com/tree/api-documentation-craft/) · 8 facets · 93 facts · page: https://llms-explorer.com/tree/10-minute-getting-started-tutorial/ ## Definitions - > **Boundary condition:** a 10-minute tutorial's cost is not the hours to write it. It is a > standing obligation to run it end-to-end against a clean environment on every release, plus > an observation channel on real users. Teams that budget only the writing cost ship a tutorial > that converts to a blocker-rated defect on the first breaking change. — [source](https://developers.google.com/tech-writing/two/sample-code) - > **Implication:** the 10-minute constraint is a *brevity* constraint applied to the one > dimension where brevity buys least, and it buys it by spending completeness and explanation > — the two dimensions where defects are rated as blockers. — [source](https://developers.google.com/tech-writing/two/sample-code) ## Structure and components - 2. **Whether "quickstart" and "getting started tutorial" are the same artifact.** The Good Docs Project separates them: a quickstart targets "domain experts who know the problem space" and carries minimal how-to content, while a getting started guide targets beginners and includes detailed conceptual information (https://www.thegooddocsproject.dev/template/quickstart). GitHub draws a different line — quickstart for people who already understand the feature, tutorial for complex tasks (https://docs.github.com/en/contributing/style-guide-and-content-model/quickstart-content-type). Diátaxis puts — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#unresolved-disagreements` - This report covers one artifact type: the short, time-boxed getting-started tutorial that sits at the front of an API's documentation and carries a new developer from zero to one verified API response. It describes the artifact's internal parts, the ordering rules that hold it together, the invariants its authors must preserve, and the points where the form breaks down. It does not cover reference documentation, how-to guides, conceptual explanation, SDK design, or developer-portal information architecture; those are separate frontier items. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#scope` - 6. The artifact's operating principle is confidence accrual: the reader is given a guaranteed small win before being asked to understand anything. "A tutorial must inspire confidence. Confidence can only be built up layer by layer, and is easily shaken." (https://diataxis.fr/tutorials/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-mechanism-why-the-form-works` - 12. The artifact serves only part of the audience by design. Developers split into systematic learners (understand first, then use) and opportunistic learners who "try to start coding immediately and search for information"; a first-success tutorial is aimed at the latter. (https://sigdoc.acm.org/cdq/how-developers-use-api-documentation-an-observation-study/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-mechanism-why-the-form-works` - 1. **How long should it be — 2, 5, or 10 minutes?** GitHub's content model says about five minutes (Claim 1); Johnson's cited exemplar says about ten (Claim 3); Young Copy's benchmark puts "Champion" under two (Claim 14). No source offers evidence that any of these thresholds is empirically optimal. The three numbers measure different spans — GitHub times a page, Young Copy times signup-to-200 — which may account for part but not all of the gap. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#unresolved-disagreements` ## How it works - **Quadruply-confirmed negative:** all four reports independently hunted for a primary source for "10 minutes" and all four failed. Four uncoordinated failures is the strongest result in the corpus. The number reaches practitioners through one exemplar — Johnson citing SendGrid — not a specification. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/rabbithole-synthesis.md#what-the-cross-read-turned-up` - **C9. This puts Diátaxis in direct tension with the empirical finding.** Diátaxis instructs tutorial authors to "ruthlessly minimise explanation," stating that "a tutorial is not the place for explanation" because "explanation distracts their attention" and "blocks their learning." — [source](https://www.cs.mcgill.ca/~martin/papers/ieeesw2015.pdf) - **C11. Obsoleteness is a blocker-rated defect** (6 examples, 6 developers), arising because "when APIs go through rapid development, their documentation can quickly become outdated." A tutorial that hard-codes a version, field name, or response shape decays without any signal to its author. — [source](https://developers.google.com/tech-writing/two/sample-code#failure-mode-silent-decay-and-a-recurring-test-cost) - 14. Repeatability. The reader must be able to repeat the steps and get the same result each time, because "repetition is a key to establishing the feeling of doing." (https://diataxis.fr/tutorials/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#invariants-the-author-must-hold` - 15. Responsibility sits entirely with the author, not the reader: "the teacher has responsibility for what the pupil is to learn, what the pupil will do in order to learn it, and for the pupil's success." (https://diataxis.fr/tutorials/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#invariants-the-author-must-hold` - 28. **Time the tutorial with a fresh-account stopwatch run before publishing any number.** The protocol exists and is cheap (Claim 13), and Diátaxis's reliability requirement can only be met "by finding out what actually happens when users do the tutorial" (Claim 7). — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#concrete-implications` ## Examples and snippets - ``` — `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/synthesis.md` … — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/rabbithole-synthesis.md` ## Measurements and reference values - - Diátaxis — Tutorials: https://diataxis.fr/tutorials/ - Tom Johnson, *Documenting APIs* — API getting started tutorials: https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html - GitHub Docs contributing guide — Quickstart content type: https://docs.github.com/en/contributing/style-guide-and-content-model/quickstart-content-type - The Good Docs Project — Quickstart Guide template: https://www.thegooddocsproject.dev/template/quickstart - Google Workspace — Google Docs API Python quickstart: https://developers.google.com/workspace/docs/api/quickstart/python - Meng, St — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#sources` - 21. Ten minutes appears in the measurement literature as an *observed outcome*, not a design target: for one API, developers took 17 minutes to a successful call unaided and 10 minutes when given a ready-to-run Postman collection — 1.7x faster. (https://blog.postman.com/improve-your-time-to-first-api-call-by-20x/, dated 2023-04-04) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-time-box-itself` ## Problems, failure modes and limitations - **Concept:** "10-minute Getting Started tutorial" (parent domain: API Documentation Craft) **Report date:** 2026-09-19 **Report type:** boundary conditions / failure modes / disagreements — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/edge-cases.md` - 15. Diátaxis names the exact error a "Getting Started" page tends to commit: "the single most common conflation made in software product documentation is that between the *tutorial* and the *how-to guide*." — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#what-the-published-standards-actually-specify` - **C1. The 10-minute figure has no basis in the dominant tutorial-design framework.** Diátaxis — the most widely adopted taxonomy for technical documentation — specifies no duration or length requirement for tutorials. Its stated success criterion is reliability, not speed: "Your tutorial ought to be so well constructed that things *can't* go wrong, that your tutorial works for every user, every time." — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/edge-cases.md#provenance-of-the-10-minutes-figure` - **C17. Developers split into two populations that one linear tutorial cannot serve simultaneously.** In an observation study with screen recording and eye tracking (11 developers, 3 organisations, 1–25 years experience), participants divided into *opportunistic* developers who "started the first task with some example code from the documentation which they then modified and extended," and *systematic* developers who explored the API and prepared the environment before starting. Time allocation: API reference 18.35%, recipes 14.99%, samples 5.69%, concepts 7.91%, with 51.06% of session time spe — [source](https://arxiv.org/abs/2310.10817) - 27. Apparent simplicity does not imply achievability. In workshops run against the SendGrid tutorial — the same ~10-minute example in claim 19 — "only few participants could successfully send the email." (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) This is the sharpest limit in the sources: the time box is a claim about the author's intent, and observed completion rates can diverge from it badly. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#limits-and-failure-modes` - **Saturation: split verdict.** Saturated on norms — the fifth style guide won't change the picture, since the finding *is* that they disagree. Not saturated on evidence: four parallel searches shared only ~30% of sources, and each still contributed 4–7 hosts no other touched. The gap further searching can't close: `edge-cases` and `practice` independently concluded that **no experiment anywhere tests a 10-minute box against any other length on any outcome.** Two reports converging on the same absence makes it real — the form's central design parameter has never been tested. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/rabbithole-synthesis.md#what-the-cross-read-turned-up` - **C21. Caveat on C20:** this study measured Stack Overflow snippets, not official quickstart code. The inference — that a quickstart which omits authentication hardening, error handling, or key management *for the sake of the 10-minute budget* exports those omissions into production — is an analogy, not a measured result. No study was located that measures production propagation of official quickstart code specifically. **This is a genuine evidence gap.** — [source](https://arxiv.org/abs/2310.10817#security-boundary-analogical-weaker-evidence) - **D1. How much explanation belongs in a getting-started tutorial.** Diátaxis: "ruthlessly minimise explanation"; explanation "blocks their learning" (https://diataxis.fr/tutorials/). Uddin & Robillard: "unexplained examples" is a top-five, blocker-rated defect (https://www.cs.mcgill.ca/~martin/papers/ieeesw2015.pdf). Google: "always prefer clarity over brevity" (https://developers.google.com/tech-writing/two/sample-code). These three cannot all be followed. No source located reconciles them, and none of the three cites the others. — [source](https://arxiv.org/abs/2310.10817#unresolved-disagreements) - **D4. How long prerequisite approval actually takes for a concrete, widely-used API.** Google's own documentation says Basic access review completes "within minutes after brand verification and submission"; trade press reported an acknowledged backlog on 2026-02-06. A tutorial author cannot state a truthful elapsed-time claim while this is unsettled. — [source](https://arxiv.org/abs/2310.10817) - - **No experiment was located that tests a 10-minute time box against a longer or shorter format on any outcome.** Every claim above is indirect: it bears on assumptions the 10-minute form depends on, not on the form itself. Treat C1–C21 as constraints on the design, not as a measured verdict. - The CHI 2024 study excludes page-view sessions shorter than 30 seconds as noise and filters dwell-time outliers outside a 1.39–961.91 minute range; its dwell times are explicitly described by the authors as over-approximations, since a reader may leave a page open while reading it from an IDE. It there — [source](https://arxiv.org/abs/2310.10817#methodological-limits-of-this-report) - 21. **[D]** Johnson enumerates six recurring causes of getting-started tutorial failure: treated as an optional extra; complex product setup; no sample application; necessary details omitted for brevity; technical complexity exceeding the writer's expertise; insufficient user testing. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#evidence-the-promise-often-fails` - 9. **The stated failure modes of getting-started tutorials are organisational, not editorial.** Johnson lists six obstacles, including that the work is treated as optional and sacrificed under deadline pressure, that product setup is too complex to demonstrate, and that the content is rarely tested against real users. (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#where-the-time-promise-breaks` - 10. **Excessive brevity is itself a named failure mode.** Among Johnson's six obstacles is a tutorial made so short that it confuses the reader — meaning the time budget can damage the artifact it is meant to discipline. (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#where-the-time-promise-breaks` - 2. **Is a time budget the right editorial control at all?** Diátaxis grounds tutorial quality in reliability and learner confidence and explicitly assigns the quickest-route objective to the how-to guide (Claims 7, 11), while the quickstart literature treats the clock as the primary constraint. Johnson's "excessive brevity" failure mode (Claim 10) sits on Diátaxis's side of this split. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#unresolved-disagreements` ## Comparisons and alternatives - **C14. At scale, tutorial/quickstart pages are *not* predominantly read by people working through them linearly.** A CHI 2024 log analysis of documentation page-view logs for 94,096 logged-in users across four Google cloud services (May 2020) found, for the guide genre (tutorial, how-to, quickstart, concept), "the opposite finding than hypothesized": the odds of accessing tutorials, how-to and similar pages were **lower**, not higher, among users with average per-page dwell times of 1–10 minutes **and** among those with dwell times over 10 minutes, compared with users whose average dwell time — [source](https://developers.google.com/tech-writing/two/sample-code#disconfirming-evidence-on-the-assumed-reader) - **C16. The active-user paradox undercuts the premise that the tutorial will be executed at all.** Carroll & Rosson (1987): users "never read manuals but start using the software immediately. They are motivated to get started and to get their immediate task done." The design implication drawn is to build for how users actually behave rather than for an idealised reader who completes preliminary training. Sources: https://www.nngroup.com/articles/paradox-of-the-active-user/ (1998-10-04) · https://research.cs.vt.edu/ns/cs5724papers/4.mental.mental.carroll.paradox.pdf (Carroll & Rosson, in *Interf — [source](https://arxiv.org/abs/2310.10817) - 3. **Whether the tutorial is the right vehicle at all.** The measured improvements in TTFC came from shipping executable artifacts — collections, generated SDKs, sandboxes — rather than from better prose (https://blog.postman.com/improve-your-time-to-first-api-call-by-20x/, https://buildwithfern.com/post/reduce-time-to-hello-world-enterprise-partners). This is not resolved by the sources: it is possible that the 10-minute tutorial is being superseded as the mechanism for first success while surviving as its packaging. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#unresolved-disagreements` - 3. **The ten-minute figure circulates in practice via named exemplars rather than via a specification.** Tom Johnson's API documentation course cites SendGrid's getting-started tutorial as designed to be completable "in about 10 minutes" and treats that as a reasonable benchmark for scope. (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-artifact-is-per-the-standards` - **Six flagged discrepancies between the reports (§8)** — conflicts in the corpus, not the world. Two matter: - **X1:** the SendGrid workshop result is "only few participants" in two reports but "of 20, only 1 succeeded" in `practice`. Same source page. A 5% completion rate against a published 10-minute promise is one of the corpus's most-cited findings and it's uncorroborated at that precision — settle before reuse. - **X2:** Young Copy is cited at two URLs, same slug, different path segment, with incompatible tiers (<5 min target vs. <2 min "Champion"). Both rows kept pending verification. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/rabbithole-synthesis.md#what-the-cross-read-turned-up` - > **Implication:** "10 minutes" appears to be a round-number convention from developer > marketing, not a threshold derived from measurement. Any claim that 10 minutes is a > boundary — rather than a memorable target — is currently unsupported. — [source](https://nordicapis.com/why-time-to-first-call-is-a-vital-api-metric/) - **C6. Enabling an API can require accepting Terms of Service and billing liability**, a step that is organisationally gated (procurement, finance approval) rather than time-gated, and therefore cannot be bounded by a tutorial author at all. — [source](https://developers.google.com/google-ads/api/docs/get-started/dev-token) - **D2. What the target duration should be, if any.** 5 minutes (Twilio, as cited) vs. under 30 minutes for a top rating (Ably scale) vs. no duration criterion at all (Diátaxis). The specific value **10 minutes** was not traced to any primary source in this review. — [source](https://arxiv.org/abs/2310.10817#unresolved-disagreements) - **D3. Whether the getting-started tutorial causes adoption or merely correlates with it.** CHI 2024 reports 3.92× odds of subsequent API use after guide-genre visits (supports the artifact), while the same paper's dwell-time model finds guide pages used predominantly as a sub-one-minute cheat-sheet rather than as a learning path (undercuts the linear-tutorial model). Both results come from the same dataset and are not reconciled by the authors. — [source](https://arxiv.org/abs/2310.10817#unresolved-disagreements) - 7. The win is deliberately minimal rather than representative. The goal is to "allow a new user to have success with your product, even if the success is small, like getting a one-line value back from an API call." (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-mechanism-why-the-form-works` - 9. Explanation is moved out of the artifact rather than shortened inside it. Authors must "ruthlessly minimise explanation" and link to detailed resources instead. (https://diataxis.fr/tutorials/) The same rule appears operationally as "link out to other articles or resources rather than replicating them." (https://docs.github.com/en/contributing/style-guide-and-content-model/quickstart-content-type) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-mechanism-why-the-form-works` - 26. The form fails most often for organisational rather than editorial reasons. Six documented causes: the tutorial is treated as optional work and deprioritised in the release cycle; product setup is too complex to be practical; no sample application exists; information omitted for brevity causes confusion; the technology exceeds the writer's capability; and the content is never tested with real users. (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#limits-and-failure-modes` - 6. **Under that classification the tutorial must be stripped of explanation.** Diátaxis states "a tutorial is not the place for explanation," and directs authors to link out rather than teach theory inline. (https://diataxis.fr/tutorials/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-artifact-is-per-the-standards` - 13. **The measurement protocol is a stopwatch test in an incognito window with a fresh account,** split into signup, first call, and success confirmation, so the tutorial is timed under genuine first-time conditions rather than by its author's estimate. (https://www.youngcopy.com/blog/how-fast-is-your-api-onboarding-benchmark-your-first-call-time-in-five-minutes/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#evaluation` - 21. **Stripe's current approach attacks the signup segment of time-to-first-call rather than the tutorial text.** Its instructions provision an anonymous sandbox with working API keys and state that no account registration is required. (https://docs.stripe.com/quickstarts) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#current-operational-practice` - 27. **Publish a word ceiling instead of a minute claim.** A 600-word limit is reviewable (Claim 2); a "10 minutes" label is an unverified assertion that user testing has broken before (Claim 8). — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#concrete-implications` - 29. **Pair the quickstart with a concepts entry point.** Two documented learner strategies (Claim 18) plus the tutorial's prohibition on explanation (Claim 6) mean the ten-minute path must link out rather than stand alone. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#concrete-implications` ## Facts and statements - **Concept:** "10-minute Getting Started tutorial" **Parent domain:** API Documentation Craft **Run date:** 2026-09-19 **Method:** `/rabbithole` (depth-first, atomic claims), scoped to the frontier brief — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md` - **B. Who is the reader?** GitHub and the Good Docs Project both scope the *quickstart* to someone who already knows the product (claims 11, 13), while Diátaxis scopes a *tutorial* to the learner acquiring basic competence (claim 14). A document titled "10-minute Getting Started tutorial" therefore names two incompatible audiences at once, and the Good Docs Project explicitly separates "getting started guide" from "quickstart" on exactly that axis (claim 13). The genre name is unresolved, not merely loose. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#unresolved-disagreements` - Terminology note: the industry uses "quickstart", "getting started guide", and "getting started tutorial" loosely and inconsistently, and the sources below disagree about whether they name one genre or three. This report treats the "10-minute getting started tutorial" as the single-path, first-success artifact regardless of which of those titles a given publisher puts on it, and flags the naming disagreement in the dedicated section. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#scope` - **Concept:** 10-minute Getting Started tutorial **Parent domain:** API Documentation Craft **Date:** 2026-09-19 **Report type:** practice (operational use, trade-offs, evaluation, implications) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md` - This report covers the *artifact* known as the 10-minute Getting Started tutorial: a time-boxed, hands-on document whose promise is that a new developer who starts at the top and follows every step reaches one working result within roughly ten minutes. It covers how teams build, budget, and measure such a document, and what it costs them. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#scope` - This report covers only the artifact itself: a short, time-boxed (~10 minute) linear Getting Started / quickstart tutorial for an API or developer product. It examines where the form breaks, what the time box costs, and what evidence contradicts the assumptions it rests on. It does **not** cover how-to guides, reference documentation, conceptual explanation, developer-relations strategy, or onboarding UX outside the tutorial page — those are separate concepts. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/edge-cases.md#scope` - 1. Kernighan, Brian W. *Programming in C: A Tutorial*, Bell Laboratories, 1974 — 2. "Hello, World!" program — Wikipedia — 3. *10 minute guide to PC computing*, Joe Kraynak, Alpha Books, 1994 — Open Library — 4. DHH, original "How to build a blog in 15 minutes with Rails" (2005) — 5. Riding Rails — Sightings — 6. Tanner, Matt. " — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#sources` - - GitHub Docs — quickstart content type (style guide and content model). https://docs.github.com/en/contributing/style-guide-and-content-model/quickstart-content-type - Diátaxis — The difference between a tutorial and how-to guide. https://diataxis.fr/tutorials-how-to/ - Diátaxis — Tutorials. https://diataxis.fr/tutorials/ - Tom Johnson, *Documenting APIs* — API getting started tutorials. https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html - Stripe Documentation — Quickstart guides. https://docs.stripe.com/quickstarts - Google developer documentation style guide — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#sources` - 1. Diátaxis — *Tutorials*. Daniele Procida. https://diataxis.fr/tutorials/ 2. Gias Uddin & Martin P. Robillard, "How API Documentation Fails," *IEEE Software* 32(4), Jul/Aug 2015, DOI 10.1109/MS.2014.80. https://www.cs.mcgill.ca/~martin/papers/ieeesw2015.pdf 3. Daye Nam, Andrew Macvean, Brad Myers & Bogdan Vasilescu, "Understanding Documentation Use Through Log Analysis: An Exploratory Case Study of Four Cloud Services," *CHI '24*, DOI 10.1145/3613904.3642721. https://arxiv.org/abs/2310.10817 4. Michael Meng, Stephanie Steinhardt & Andreas Schubert, "How Developers Use API Documentation: An Ob — [source](https://arxiv.org/abs/2310.10817#sources) - 13. The Good Docs Project treats *quickstart* and *getting started guide* as distinct types: quickstarts target domain experts with minimal how-to content for the primary feature; getting started guides target beginners with detailed conceptual information. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#what-the-published-standards-actually-specify` - 20. **[D]** Empirical counter-evidence from a controlled setting: Tom Johnson had workshop participants attempt SendGrid's getting-started tutorial in about 10 minutes, and "only few participants could successfully send the email." — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#evidence-the-promise-often-fails` - **A. How long is a getting-started tutorial supposed to take?** Sources conflict by more than an order of magnitude and none cites the others: ~5 minutes / 600 words (GitHub, claim 10) · ~10 minutes (vendor practice, claim 18) · 1–2 hours (Good Docs Project, claim 12) · unspecified by design (Diátaxis, claim 14). Left side by side, not averaged. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#unresolved-disagreements` - 19. The "10 minutes" in the concept's name is a genre convention with no single authority behind it. The nearest anchor in the technical-writing literature is a worked example — the SendGrid email tutorial, described as completable "in about 10 minutes." (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-time-box-itself` - 1. **The time budget is not agreed, and the disagreement spans an order of magnitude.** GitHub's content model specifies "about five minutes or 600 words" (https://docs.github.com/en/contributing/style-guide-and-content-model/quickstart-content-type). The Good Docs Project template specifies completion "within 1 - 2 hours with a preference for a shorter time" (https://www.thegooddocsproject.dev/template/quickstart). Diátaxis states no timing rule at all (https://diataxis.fr/tutorials/). Google's own quickstart pages carry no time estimate (https://developers.google.com/workspace/docs/api/quick — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#unresolved-disagreements` - 1. **The 10-minute budget is a convention, not a standard; published style guides set the budget lower.** GitHub's content model defines the quickstart content type as completing "a discrete, focused task by illustrating a workflow with only essential steps, in about five minutes or 600 words," and directs authors to a tutorial instead for more complex tasks. (https://docs.github.com/en/contributing/style-guide-and-content-model/quickstart-content-type) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-artifact-is-per-the-standards` - 8. **Published completion times are frequently unverified and can be wrong by an order of magnitude.** Johnson reports that of 20 workshop participants attempting SendGrid's ~10-minute tutorial, "only 1 managed to do the tutorial successfully." (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#where-the-time-promise-breaks` - 18. **Developers split into two learning strategies after forming a global understanding of an API: concepts-oriented and code-oriented.** Documentation must serve both, which a single code-first ten-minute path does not. (https://journals.sagepub.com/doi/10.1177/0047281617721853) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-tutorial-cannot-fix` - - ~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/synthesis.md — new: cross-report synthesis, 40 sources, split saturation verdict — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/rabbithole-synthesis.md#files` - 1. the **artifact** (a tutorial page a reader works through), and 2. the **metric** it is usually justified by (time-to-first-call / time-to-first-hello-world). — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/edge-cases.md#scope` - **C2. Practitioner time targets disagree by roughly a factor of six, and 10 minutes is not among the published anchors.** Twilio is cited as having aimed for developers to "get up and running in 5 minutes or less," while Ably's published time-to-hello-world scale awards its top rating (5/5) to anything **under 30 minutes**, 4/5 to 30–60 minutes, and 1/5 to over 4 hours. Source: https://nordicapis.com/why-time-to-first-call-is-a-vital-api-metric/ (2021-11-09) — [source](https://diataxis.fr/tutorials/) - > **Boundary condition:** a 10-minute claim is defensible only for the *post-credential* > segment. Where credentials require human or organisational approval, the honest unit is > "10 minutes of reader effort," not "10 minutes elapsed." Reports that conflate the two are > measuring a different quantity than the reader experiences. — [source](https://support.google.com/googleapi/answer/6158867?hl=en) - **C12. Diátaxis states that tutorial flaws are undiscoverable by the author alone.** "Your tutorial will have flaws and gaps, however carefully it is written. You won't discover them all by yourself, you will have to rely on users to discover them for you," and the only way to learn what they are is "through extensive testing and observation." — [source](https://www.cs.mcgill.ca/~martin/papers/ieeesw2015.pdf) - **C15. Completing a short tutorial does not imply adoption.** In the same dataset, Cluster 21 (4,170 users) consisted of users with **no** platform experience and **no** product experience who spent roughly 6 minutes predominantly on Tutorial documentation, mostly with "clarifying" intent, and made **no subsequent API requests**. — [source](https://developers.google.com/tech-writing/two/sample-code#disconfirming-evidence-on-the-assumed-reader) - **In scope.** The documentation genre itself: where the time-boxed "get something working fast" tutorial came from, how the published content-type standards define it, what duration each one actually specifies, and what evidence exists about whether the time promise holds. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#scope` - **Terminology note.** Three names circulate for overlapping artifacts — *quickstart*, *getting-started guide*, and *tutorial*. They are **not** synonyms in the published standards. This report keeps each source's own term and flags where they conflict (see Disagreements). — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#scope` - 1. The convention of "first program prints a trivial success message" is fixed by Brian W. Kernighan's 1974 Bell Laboratories memo *Programming in C: A Tutorial*, whose first example is `main( ) { printf("hello, world"); }`, introduced as "A Simple C Program." — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#the-genre-s-ancestors` - 2. The earlier documented instance is Kernighan's 1972 *A Tutorial Introduction to the Language B*; the example became universal only after Kernighan & Ritchie's *The C Programming Language* (1978). — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#the-genre-s-ancestors` - 3. Packaging technical instruction explicitly in ten-minute units predates web API documentation by roughly a decade: Alpha Books published *10 minute guide to PC computing* (Joe Kraynak) in 1994, one title in a broad "10 Minute Guide" series of short, goal-oriented lessons. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#the-genre-s-ancestors` - 10. GitHub's content model sets the tightest published budget: "Quickstarts enable people to quickly complete a discrete, focused task by illustrating a workflow with only essential steps, in about five minutes or 600 words." Anything more complex is routed to a tutorial. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#what-the-published-standards-actually-specify` - 14. **[D]** Diátaxis, the most widely adopted documentation taxonomy, defines a tutorial purely by orientation — "A tutorial is always **learning-oriented**", serving "the user's *acquisition* of skills and knowledge" — and specifies no duration whatsoever. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#what-the-published-standards-actually-specify` - 16. Diátaxis sets a success criterion orthogonal to elapsed minutes: "What matters in a tutorial is what the learner *does*, and what they experience while doing it." — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#what-the-published-standards-actually-specify` - 18. The literal ten-minute promise is live in shipping first-party API documentation. LiveKit's voice AI quickstart states: "Build and deploy a simple voice assistant in less than 10 minutes," repeated as "In less than 10 minutes, you'll have a voice assistant that you can speak to in your terminal, browser, telephone, or native app." — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/history.md#the-ten-minute-promise-in-current-practice` - 11. The same study locates the problem the artifact solves: "identifying appropriate entry points into the API and relating particular tasks to specific elements" was a key obstacle for initial learning regardless of developer experience. The getting-started tutorial is an externally-supplied entry point. (https://sigdoc.acm.org/cdq/how-developers-use-api-documentation-an-observation-study/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-mechanism-why-the-form-works` - 13. No choices. The author must "ignore options and alternatives" — a branch in the path breaks the single-path property. (https://diataxis.fr/tutorials/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#invariants-the-author-must-hold` - 16. Verified success rate. "Make sure the tutorial actually works and provides the advertised result, with as high of a success rate as possible" — which makes the artifact a tested asset, not prose. (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#invariants-the-author-must-hold` - 25. In an enterprise-integration context, the reductions attributed to TTFC improvement come from generating SDKs, runnable docs, and sandbox access from the API definition so partners self-serve — again relocating effort out of the tutorial text. (https://buildwithfern.com/post/reduce-time-to-hello-world-enterprise-partners) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/mechanism.md#the-time-box-itself` - Out of scope and deliberately not researched: sibling documentation types (how-to guides, reference, explanation, conceptual overviews) except where a source uses them to define the boundary of a getting-started tutorial; the parent domain API Documentation Craft as a whole; and adjacent concepts such as sandbox provisioning, SDK generation, or developer-relations metrics programs in general. Time-to-first-call appears here only as the evaluation instrument for this artifact, not as a topic in its own right. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#scope` - 4. **The canonical shape is four steps: register, get credentials, make one request, read the response.** Johnson describes the target as "a kind of Hello World tutorial with the API," producing "the simplest possible output with the system." (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-artifact-is-per-the-standards` - 5. **Diátaxis classifies this artifact as a tutorial, which constrains its content.** A tutorial serves the user "at study," follows "a carefully-managed path," and takes place in a contrived setting; a how-to guide serves the user "at work" and takes the quickest route to a result. (https://diataxis.fr/tutorials-how-to/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-artifact-is-per-the-standards` - 7. **The binding obligation is reliability, not brevity.** Diátaxis requires that the tutorial "works for every user, every time," and notes that a learner who follows the directions and does not get the expected result "will quickly lose confidence, in the tutorial, the tutor and themselves." (https://diataxis.fr/tutorials/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-artifact-is-per-the-standards` - 11. **Diátaxis does not endorse speed as a tutorial goal.** Its guidance frames tutorial quality as a complete, confidence-building learning journey and assigns the quickest-route objective to the how-to guide instead. (https://diataxis.fr/tutorials-how-to/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#where-the-time-promise-breaks` - 17. **The severest documented problems with API documentation are ambiguity, incompleteness, and incorrectness of content** — properties of the whole documentation set, which a getting-started tutorial does not address. The finding comes from two surveys of 323 professional developers plus analysis of 179 API documentation units. (https://dl.acm.org/doi/abs/10.1109/MS.2014.80) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-tutorial-cannot-fix` - 19. **A code-first quickstart therefore serves only one of the two documented strategies.** The concepts-oriented developer needs the explanation that Diátaxis requires the tutorial to omit (Claim 6), so the artifact is by construction incomplete for that reader. (https://journals.sagepub.com/doi/10.1177/0047281617721853 ; https://diataxis.fr/tutorials/) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#what-the-tutorial-cannot-fix` - 23. **Removing setup burden is longstanding advice, not a Stripe invention.** Johnson's course recommends sandbox accounts or pre-configured data precisely so the tutorial does not spend its budget on setup. (https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#current-operational-practice` - 24. **"Quickstart," "tutorial," and "codelab" are accepted as distinct named documentation types in Google's style guide,** so the label carries a reader expectation and should be chosen deliberately. (https://developers.google.com/style/highlights) — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#current-operational-practice` - Known limits of this evidence base: the Uddin & Robillard (2015) and Meng et al. (2018) findings were read from abstract-level sources, not full text — the PDF extractions failed — so no figure or table from either paper is cited here. The arXiv log-analysis paper is likewise cited at abstract level, which is why Disagreement 5 stays open. No source examined runs a controlled experiment on tutorial length itself; every time threshold reported above is a convention or a practitioner benchmark, not an experimental result. That absence is the single largest gap in the evidence for this concept. — source: `~/.global-ai-hub/research-runs/frontier-current/10-minute-getting-started-tutorial/reports/practice.md#quality-gate` ## Related concepts - tutorial — is a part of 10-minute Getting Started tutorial - 10-minute — is a part of 10-minute Getting Started tutorial - Started — is a part of 10-minute Getting Started tutorial - Getting — is a part of 10-minute Getting Started tutorial