developer-tutorial

{
  "skill_name": "developer-tutorial",
  "evals": [
    {
      "id": 1,
      "prompt": "I'm docs lead at Quillrail, a hosted vector-search API. Marketing wants a tutorial called \"Deploy Quillrail to production\" live for our launch. Here's the coverage they asked for: deploying on AWS, GCP or Azure; provisioning with either Terraform or the web console; wiring it to Postgres or MongoDB depending on what the customer already runs; and a closing section on tuning index size for high-volume versus low-volume workloads. Readers are backend engineers who already ran our quickstart. Can you draft the tutorial outline?",
      "expected_output": "A scope call that classifies the requested artefact as a how-to rather than a tutorial, names each fork, routes it to the how-to skill, and offers a genuine tutorial alternative pinned to one environment.",
      "files": [],
      "expectations": [
        "Classifies the requested artefact as a how-to guide, not a tutorial.",
        "Draws the distinction as learning-oriented (serving the reader at study) versus task-oriented (serving the reader at work).",
        "Attributes the tutorial/how-to distinction to Diátaxis.",
        "States that conflating the two is described as the single most common conflation made in software product documentation.",
        "Names each of the four branch points in the request (cloud provider, Terraform versus console, Postgres versus MongoDB, workload tuning) as forks a tutorial cannot carry.",
        "States that every imported fork destroys the tutorial's single guaranteed path.",
        "Makes the scope call out loud instead of silently absorbing the request and producing a branching tutorial.",
        "Routes the branching artefact to a how-to guide, naming it as the owner of the other answer.",
        "Cites the ban on presenting choices in a tutorial (Diátaxis' don't-list: abstraction and generalisation, explanation, choices, excess information).",
        "Any tutorial alternative it proposes pins exactly one environment: one cloud, one provisioning method, one database, with versions stated.",
        "Produces no outline section shaped as \"if you use X… if you use Y…\" on the main path.",
        "States the learning objective of any proposed tutorial as a demonstrable capability the learner performs, not as \"understand deployment\"."
      ]
    },
    {
      "id": 2,
      "prompt": "Here's the tutorial I drafted for Nomadic Labs' event-streaming SDK. Nine steps: (1) install the CLI, (2) tour of the config file, (3) create a stream, (4) list your streams, (5) create a consumer group, (6) tour of the admin dashboard, (7) publish an event, (8) consume it, (9) overview of our other SDKs. It's written and peer-reviewed already. I just need you to add a learning objective at the top and a summary at the bottom so it reads like a proper tutorial. Audience is backend devs who've used our REST API but never the streaming SDK.",
      "expected_output": "A refusal to retrofit an objective onto finished steps, a backward-design rewrite order, a diagnosis of the draft as a feature tour, and deletion of the steps that serve no objective.",
      "files": [],
      "expectations": [
        "Declines to write the learning objective to fit the nine steps that already exist.",
        "States the required order: learning objective first, then the evidence (final checkpoint and transfer test), then the steps.",
        "Names backward design as the framework and attributes it to Wiggins & McTighe, Understanding by Design.",
        "Diagnoses the draft as a feature tour with a learning-shaped title, because the steps were chosen by what the product does rather than what the learner needs.",
        "Proposes a learning objective phrased as a verb the learner performs and testable by asking them to do it.",
        "Uses the Good Docs Project phrasing \"By the end of this tutorial, you'll be able to…\" for the objective.",
        "Rejects \"understand\" or \"learn about\" style objective wording as untestable.",
        "Names the steps that do not serve the objective (the config-file tour, the admin dashboard tour, the other-SDKs overview) and recommends deleting them rather than keeping them.",
        "Defines the final checkpoint and the unaided variation before redrafting any step.",
        "Notes the draft carries no checkpoints, and places them every 3-5 steps as a baseline.",
        "States the summary must restate capabilities the learner now has, worded differently from the objectives, rather than topics the page covered.",
        "Counts nine primary steps against the Good Docs Project's seven-primary-step maximum and flags the overrun."
      ]
    },
    {
      "id": 3,
      "prompt": "Our \"build a rate limiter with Kestrelo\" tutorial has 8 steps. Reader feedback says step 6 onward is \"too hard\", so my plan is to hand over the complete file at every step the way we already do in steps 1 and 2, and add a \"copy full solution\" button under steps 6, 7 and 8. Separately, I only have time to author two kinds of hint, so I'd do pseudocode plus the full solution since those are fastest to write. Readers are mid-level Python devs. Thoughts before I start?",
      "expected_output": "A rejection of the flat full-file plan in favour of a fading schedule, plus a reversal of the hint-rung choice ranked by value per authoring hour.",
      "files": [],
      "expectations": [
        "Rejects handing the complete file at every step, stating that a tutorial copy-pasting as much at the last step as at the first has taught nothing.",
        "Prescribes fading across three stages: full file with all imports early, only the added lines in a named file with the insertion point stated in the middle, and the requirement plus expected output late.",
        "Names guidance fading as a cognitive-load result and attributes it to Renkl (and Atkinson).",
        "States that the three-stage early/middle/late split is a self-set baseline shape, not part of the published finding.",
        "Rejects the \"copy full solution\" button on the late steps as removing the step that produces transferable skill.",
        "Ranks the four hint rungs by value per authoring hour as: blanked solution, then pointer, then full solution, then pseudocode.",
        "Recommends authoring the blanked solution and the pointer, and rejects the proposed pseudocode-plus-full-solution pair.",
        "States the blanked block is the full solution minus about three lines and teaches the most.",
        "States pseudocode must be rewritten on every API change and says only what the blanked block already says.",
        "Attributes the blanked-block rung to the completion-problem effect (Paas, 1992).",
        "Distinguishes the learner's escalation order (pointer, pseudocode, blanked solution, full solution) from the authoring priority order.",
        "Ties late-step fading to the learner being able to perform the objective unaided on a variation they were never walked through.",
        "Treats the \"too hard from step 6\" feedback as a possible fading or one-new-thing-per-step defect rather than accepting more complete code as the fix."
      ]
    },
    {
      "id": 4,
      "prompt": "Planning the tutorial for Brightwake's webhooks SDK: \"receive and verify a webhook\". Scoping call gave me this. It has to be live for our launch on the 19th, which is next Friday. Leadership called it a one-off launch asset, not something the docs set will build on. Nobody on the team is assigned to own the page after launch. I have roughly 6 hours of writing time. The eng lead wants it to include Docker Compose, a GitHub Actions workflow, pytest with coverage, structured logging config, and a step where the learner pipes in their own production webhook payloads from a sandbox we haven't built yet. Audience: backend devs who did the quickstart. What's the plan?",
      "expected_output": "A concept-ladder plan that names the stop rung explicitly, deletes the polish and robustness rungs against the interview answers, and refuses the real-data step.",
      "files": [],
      "expectations": [
        "Applies a layered concept ladder (skeleton, core concept, real data, robustness, polish) to decide where to stop.",
        "States that skeleton and core concept are not optional, because without them the objective is unmet.",
        "States that the ladder's row order is the build order, not the ranking.",
        "Deletes the polish rung outright (Docker Compose, CI workflow, pytest, logging config) rather than parking it at the bottom of the plan, because the page has no named owner.",
        "Gives the reason for deleting rather than deferring: an unowned rung reappears as scope and then rots.",
        "Deletes the robustness rung, the companion repository and CI-run checkpoints, because leadership called the page a one-off rather than a compounding asset.",
        "Rejects the learner's own production payloads (the real data rung) because no sandbox exists, so the rung is not near-free.",
        "Names the condition that would promote the real data rung: the learner's own input being what the objective names, or an existing sandbox making it near-free.",
        "States the chosen stop rung explicitly rather than leaving it implied by what was cut.",
        "States a ranking out loud (for example core concept above robustness above real data above polish on efficiency) rather than implying it by row order.",
        "Notes that real data drags fixtures, a seed script and a sandbox that drift whenever the schema moves, while robustness costs one error path that survives releases.",
        "Names the deadline, the one-off framing and the absent owner as the interview answers that moved each rung, rather than presenting the ranking as fixed."
      ]
    },
    {
      "id": 5,
      "prompt": "Kaviro's docs team here. We shipped a tutorial for our agents SDK last month. Measurement plan: completion rate with a 40% target, since that's the industry standard I keep seeing quoted, plus a thumbs-up/thumbs-down widget at the bottom of the page, plus a quarterly NPS question about docs. Our VP is asking the education function to justify its two headcount at the board review in six weeks. Instrumentation budget is basically a few days of one engineer. Is this plan good?",
      "expected_output": "A Kirkpatrick-sorted critique that refuses the imported completion target, promotes the transfer test and per-checkpoint drop-off first, and promotes the behaviour-share metric because of the headcount question.",
      "files": [],
      "expectations": [
        "Sorts the proposed metrics with Kirkpatrick's four levels and identifies completion rate, the thumbs widget and the NPS question as level 1 (reaction) only.",
        "Names the documented trap: teams measure levels 1-2 and stop, so a tutorial with a strong completion rate and no behaviour change looks like a success for years.",
        "Refuses the 40% external completion target, stating there is no trustworthy published completion benchmark for developer tutorials.",
        "Prescribes comparing each figure against this tutorial's own previous version instead of an outside number.",
        "Recommends the transfer-test pass rate from the cold runs and identifies it as level 2 (learning).",
        "States the transfer-test pass rate costs near-zero to wire because the cold-run pass threshold already runs the test; only the result is recorded.",
        "Recommends per-checkpoint drop-off, costing roughly an hour to wire, since the checkpoints already exist.",
        "States that one dominant abandonment checkpoint marks a broken step rather than a hard concept, so that step gets fixed before the concept is rewritten around it.",
        "Promotes the level-3 behaviour share (completers who perform the same task in the product within a week) above the rest, because the page is being asked to justify its own headcount.",
        "States that the identity plumbing joining the learning surface to the product must land before publishing, or the first cohort is unmeasurable.",
        "States that completion rate and median completion time tie on both value and wiring effort, because they are two readings of the same start-and-finish event pair.",
        "Names the default order (instrument the first two, read the third) and says explicitly that the headcount question overrides it.",
        "States that completion rate says nothing about whether anyone learned."
      ]
    },
    {
      "id": 6,
      "prompt": "Quick one. Our webhooks tutorial on docs.trelvin.io gets about 4,000 visits a month and analytics say 11% reach the last page. I've read it through three times and my notes are: it's a bit long, the tone is dry, step 4 (signature verification) is probably where people get lost because it's the most complex part, and it needs screenshots. Can you turn that into a revision plan I can hand to a writer this week? We don't have time for user testing.",
      "expected_output": "A refusal to rewrite from reading, a specified cold-run protocol, and an audit hand-back defined as a step-keyed table ordered by learners blocked.",
      "files": [],
      "expectations": [
        "Declines to produce the revision plan from reading alone, and requires cold runs before any rewrite.",
        "Specifies runners who match the tutorial's declared audience level, and excludes the author and ideally the author's team.",
        "Specifies the audit deliverable as a table rather than prose.",
        "Defines the table columns as step number, what breaks, the event kind, and the fix.",
        "Names all four event kinds: defect, hidden prerequisite, concept gap, friction.",
        "Orders the rows by how many learners each step blocks, not by page order.",
        "Labels \"step 4 is probably where people get lost\" as a guess from reading rather than an observation.",
        "Rejects \"add more explanation\" at step 4 as the fix, on the grounds that explanation is what blocks learning in a tutorial.",
        "Treats the screenshots and tone notes as cosmetics to confirm against observed hesitation rather than rewrite on assumption.",
        "States that anything a runner \"figured out\" is logged as a defect, not a success.",
        "Specifies that the observer stays silent during the run and does not answer the runner's questions.",
        "Sends the revision through one more cold run before publishing.",
        "Recommends per-checkpoint instrumentation so the 11% figure localises to a step instead of a page."
      ]
    },
    {
      "id": 7,
      "prompt": "Ready to verify the tutorial before we publish. The plan: Marcus, who wrote the tutorial and also wrote the SDK, runs it on his laptop against the current main-branch build so we catch anything unreleased too. I'll sit next to him and answer questions as they come up so we don't waste an afternoon. The tutorial is declared beginner-level but Marcus is our most senior engineer, so he'll move fast. If he reaches the end in under an hour, we ship. Sound right?",
      "expected_output": "A point-by-point rejection of the proposed verification setup, replaced with a level-matched cold-run protocol, clean environment, published-artefact install, and a transfer test as the real ship gate.",
      "files": [],
      "expectations": [
        "Rejects the author as runner, and excludes the author's team where possible.",
        "Rejects a senior engineer as runner for a beginner-declared tutorial, stating they patch the gaps unconsciously and report success.",
        "Requires the runner to match the declared audience level.",
        "Rejects the observer answering questions, stating it destroys the data point the run exists to collect.",
        "Requires the runner to narrate aloud while the observer stays silent and takes notes.",
        "Rejects running against the working tree or the main-branch build, and requires installing from the published artefact (released package or image).",
        "Requires a clean machine or fresh container: no cached credentials, no globally installed toolchain, no leftover project directory.",
        "Adds a run on one version newer than the declared runtime versions, to see how loudly it breaks.",
        "Recommends two runners rather than one: a first-time evaluator and someone already fluent in the ecosystem.",
        "Requires timestamping the start of each step and each checkpoint, treating the gap between timestamps as the friction measurement.",
        "Requires recording every hesitation, re-read, scroll-back and tab-switch away from the page.",
        "Requires letting failures play out, because the recovery path is part of the artefact under test.",
        "Rejects \"reaches the end in under an hour\" as the ship gate and requires the transfer test: roughly ten minutes after the last checkpoint, the runner performs the objective on a variation never demonstrated, with reference docs and no help."
      ]
    },
    {
      "id": 8,
      "prompt": "I've been reading about desirable difficulty and retrieval practice and I want to apply it to Hollowpine's \"build a job queue\" tutorial. My plan: (1) remove the exact expected-output blocks so learners have to reason about what should happen, (2) leave a deliberate off-by-one bug in step 3 so they have to debug it, (3) stop pinning the Node version in prerequisites so they work out their own environment, (4) in step 5, describe the goal vaguely so they have to interpret the requirement themselves. Learners are bootcamp grads. Will this raise retention?",
      "expected_output": "A rejection of all four changes on the main path, with the reliability/difficulty boundary explained and the legitimate placement for difficulty specified.",
      "files": [],
      "expectations": [
        "Rejects all four proposed changes as applied to the tutorial's main path.",
        "States that the main path (environment, commands, the code the learner types) is governed by reliability, and every failure there is the author's defect.",
        "Cites Diátaxis on a tutorial having to inspire confidence and being so well constructed that it works for every user, every time.",
        "States that difficulty created by omission or ambiguity is not desirable difficulty, and the learner absorbs it as their own failure.",
        "Attributes desirable difficulty to Bjork and defines it as difficulty that slows acquisition but raises long-term retention.",
        "Keeps exact expected output from a real run in every step and checkpoint.",
        "Keeps the pinned Node version in prerequisites, with a check command for the row.",
        "Keeps step 5's requirement stated precisely, rejecting deliberate vagueness.",
        "States where difficulty may legitimately go: optional, clearly marked additions placed after a passed checkpoint, with the answer available.",
        "Names the permitted difficulty forms: predicting an output before running it, breaking something on purpose and reading the error, extending the feature by one parameter.",
        "Rejects the deliberate off-by-one bug on the main path, converting it at most into a marked optional break-it-on-purpose exercise after a checkpoint.",
        "States that one step that fails costs more than three that succeed earn, because the learner concludes they are not smart enough and leaves.",
        "Explains that reliability and desirable difficulty are not contradictory because they govern different parts of the page."
      ]
    },
    {
      "id": 9,
      "prompt": "I'm writing Ardenmoor's documentation style guide and I want a \"Tutorials\" section of numbered company standards, each one citing its industry source so nobody re-litigates it in review. The rules I want codified: checkpoints every 3-5 steps, tutorials run 15-60 minutes, maximum 7 primary steps, maximum 4 substeps per step, minimum 55% completion rate, fading in three stages (full code, then diff, then requirement), and weekly CI on the companion branches. Can you write it up with the citations?",
      "expected_output": "A style-guide section that splits the rules into sourced versus self-set, refuses the invented completion benchmark, and supplies the real published comparables.",
      "files": [],
      "expectations": [
        "Splits the listed rules into those with a published source and those that are self-set defaults, instead of citing a source for all of them.",
        "Attributes the 15-60 minute range to the Good Docs Project tutorial template.",
        "Attributes the seven-primary-step maximum to the Good Docs Project tutorial template.",
        "Attributes the four-substep maximum to the Good Docs Project tutorial template.",
        "Identifies checkpoint spacing of every 3-5 steps as a self-set default with no published source.",
        "Identifies the three-stage fading split as self-set, while noting guidance fading itself is a published effect.",
        "Identifies the weekly companion-branch CI cadence as a self-set default and recommends matching it to the release train instead.",
        "Refuses the 55% completion-rate standard, stating no trustworthy published tutorial completion benchmark exists.",
        "Notes that the activation-style benchmarks quoted in developer-marketing material are self-reported vendor signup-funnel numbers, not tutorial numbers.",
        "Offers published comparables for checkpoint spacing: Diátaxis arguing every step should produce a comprehensible result, Google Codelabs constraining a codelab to five to ten steps, freeCodeCamp's two-minute rule.",
        "States that Renkl and Atkinson's own experimental designs fade continuously rather than in three fixed stages.",
        "Warns that presenting a self-set number as an industry standard leaves the team defending a figure nobody can source.",
        "Recommends labelling each rule in the style guide as sourced or self-set, so a reviewer can tell which ones are negotiable."
      ]
    },
    {
      "id": 10,
      "prompt": "Internal tool. The tutorial is \"Deploy a service with Grellan\", our in-house deploy platform. Every new backend hire must complete it in their first week; they can't skip it. The first cold run with a new hire took 95 minutes across 11 primary steps. The platform needs VPN access, membership of an SSO group, and a namespace that a platform engineer provisions by ticket - for the run we just handed the hire a pre-provisioned account. About half the commands hit our internal registry, which isn't reachable outside the office network. Their manager wants proof they completed it. What do I change?",
      "expected_output": "A split at a checkpoint, the internal/enterprise audience branch applied, access named before step 1, offline command variants, reviewer-visible checkpoints, and the polish rung promoted.",
      "files": [],
      "expectations": [
        "Splits the tutorial at a checkpoint into two tutorials with a stated order, rather than trimming prose to fit the time budget.",
        "Names the 15-60 minute range as the sourced ceiling the 95-minute run breaks, while noting that splitting rather than trimming is a judgement call.",
        "Flags 11 primary steps against the seven-primary-step maximum.",
        "Applies the internal or enterprise audience branch rather than the self-serve individual-learner branch.",
        "States that the failure mode for this audience is silent misunderstanding rather than a closed tab, because the learner cannot abandon.",
        "Requires naming the access needed (VPN, SSO group membership, provisioned namespace) and who grants it, before step 1.",
        "Requires an offline or on-prem variant of every command that assumes internet or external registry access.",
        "Adds checkpoints the learner can show a reviewer, answering the manager's proof requirement.",
        "Rejects the pre-provisioned account for verification runs and requires at least one runner to go through the real access request.",
        "Promotes the polish rung of the concept ladder, because the production shape is the objective when a tutorial doubles as onboarding onto an internal tool.",
        "Does not apply the self-serve rules (front-loading the visible result against abandonment, keeping the path inside a free tier, holding billing prompts until after the last checkpoint).",
        "Keeps the objective, the ladder and the checkpoint structure identical to any other tutorial, changing only what the audience context requires.",
        "Classifies the access requirements as hidden prerequisites if they surfaced after step 1, and moves them into \"Before you begin\" with a check command."
      ]
    }
  ],
  "trigger_queries": [
    {
      "query": "Write a tutorial that teaches people to stream responses from our SDK",
      "should_trigger": true
    },
    {
      "query": "We need a hands-on guide for our webhooks where readers can do it themselves afterwards",
      "should_trigger": true
    },
    {
      "query": "Nobody finishes our tutorial. Can you work out why and fix it?",
      "should_trigger": true
    },
    {
      "query": "I want a learn-by-building article: build a small task API with our database client",
      "should_trigger": true
    },
    {
      "query": "Draft a build-along guide for our CLI",
      "should_trigger": true
    },
    {
      "query": "Can you write the lab handout for our training day?",
      "should_trigger": true
    },
    {
      "query": "Our conference workshop needs a printable handout with steps and checkpoints",
      "should_trigger": true
    },
    {
      "query": "Write lesson 3 of our developer course, on rate limiting",
      "should_trigger": true
    },
    {
      "query": "Is this page a tutorial or a how-to? I honestly can't tell anymore",
      "should_trigger": true
    },
    {
      "query": "My step-by-step guide branches on macOS vs Linux vs Windows and it's a mess",
      "should_trigger": true
    },
    {
      "query": "People finish our guide and still can't do the thing on their own",
      "should_trigger": true
    },
    {
      "query": "How often should I put verification steps into a teaching guide?",
      "should_trigger": true
    },
    {
      "query": "Everyone drops off at exactly the same step of our walkthrough",
      "should_trigger": true
    },
    {
      "query": "I want readers producing code by the end, not pasting mine",
      "should_trigger": true
    },
    {
      "query": "Our teaching page runs 90 minutes. What do I cut?",
      "should_trigger": true
    },
    {
      "query": "Turn our internal deploy-tool onboarding doc into something a new hire can follow alone",
      "should_trigger": true
    },
    {
      "query": "Write a guide that teaches someone to verify a webhook signature by building it",
      "should_trigger": true
    },
    {
      "query": "Review this tutorial before we publish it",
      "should_trigger": true
    },
    {
      "query": "What should the learning objective of this page be?",
      "should_trigger": true
    },
    {
      "query": "How do I make my guide teach instead of just demo the product?",
      "should_trigger": true
    },
    {
      "query": "Can you audit the tutorial series in our docs?",
      "should_trigger": true
    },
    {
      "query": "What's a good checkpoint to put after the database step?",
      "should_trigger": true
    },
    {
      "query": "We want a \"build your first integration\" page",
      "should_trigger": true
    },
    {
      "query": "How do I stop learners copy-pasting all the way to the end?",
      "should_trigger": true
    },
    {
      "query": "Help me plan a hands-on lab for our user conference",
      "should_trigger": true
    },
    {
      "query": "Write the teaching page for our new streaming API, aimed at people who already did the quickstart",
      "should_trigger": true
    },
    {
      "query": "Each step of my guide builds on the last - how do I sequence the concepts?",
      "should_trigger": true
    },
    {
      "query": "Our walkthrough assumes too much and beginners get stuck at step 2",
      "should_trigger": true
    },
    {
      "query": "Should the final step hand them the full code or make them write it?",
      "should_trigger": true
    },
    {
      "query": "How long should a teaching guide for developers be?",
      "should_trigger": true
    },
    {
      "query": "Write a step-by-step that ends with the reader able to do it again unaided",
      "should_trigger": true
    },
    {
      "query": "Our workshop handout gives people no way to check they're on track",
      "should_trigger": true
    },
    {
      "query": "Design the exercise progression for our developer training module",
      "should_trigger": true
    },
    {
      "query": "What belongs in the \"before you begin\" section of a teaching guide?",
      "should_trigger": true
    },
    {
      "query": "How do I tell whether our teaching guide actually built a skill, or just got finished?",
      "should_trigger": true
    },
    {
      "query": "We have a companion repo but the branches no longer match the written steps",
      "should_trigger": true
    },
    {
      "query": "Write a guide teaching devs to add pagination to an endpoint with our ORM",
      "should_trigger": true
    },
    {
      "query": "Our tutorial hasn't been run since the 2.0 release and I think it's broken",
      "should_trigger": true
    },
    {
      "query": "Rewrite step 4 - two new concepts land at once and people get lost",
      "should_trigger": true
    },
    {
      "query": "I need a guide where the reader builds a working thing while learning the concept",
      "should_trigger": true
    },
    {
      "query": "Our teaching page ships a Dockerfile, CI config and a test suite. Is that too much?",
      "should_trigger": true
    },
    {
      "query": "Help me test our guide with a real learner before we publish",
      "should_trigger": true
    },
    {
      "query": "Who should run our guide end to end before it goes live?",
      "should_trigger": true
    },
    {
      "query": "Write a guide that takes someone from \"never used this\" to \"can do it themselves\"",
      "should_trigger": true
    },
    {
      "query": "Our code blocks say \"you should see something like this\" with no actual output",
      "should_trigger": true
    },
    {
      "query": "Break our 11-step guide into something manageable",
      "should_trigger": true
    },
    {
      "query": "Write the teaching article for our OAuth flow",
      "should_trigger": true
    },
    {
      "query": "The recovery lines in our tutorial read like they're blaming the learner - fix them",
      "should_trigger": true
    },
    {
      "query": "Plan a self-paced hands-on module our engineers can do in an hour",
      "should_trigger": true
    },
    {
      "query": "How should I fade the amount of code I hand over as the guide goes on?",
      "should_trigger": true
    },
    {
      "query": "The team wants a \"learn X by building Y\" post for launch week",
      "should_trigger": true
    },
    {
      "query": "Our guide is written for beginners and experts at the same time and serves neither",
      "should_trigger": true
    },
    {
      "query": "I have the steps written, now I need the objective and the summary",
      "should_trigger": true
    },
    {
      "query": "Draft a hands-on guide for our Terraform provider",
      "should_trigger": true
    },
    {
      "query": "We want optional exercises after each section that actually make people think",
      "should_trigger": true
    },
    {
      "query": "What's the right way to write expected output in a teaching guide?",
      "should_trigger": true
    },
    {
      "query": "Our docs page teaches nothing - people finish it and can't repeat any of it",
      "should_trigger": true
    },
    {
      "query": "Set up a way for someone to resume our long guide tomorrow without restarting",
      "should_trigger": true
    },
    {
      "query": "Write a quickstart that gets someone to their first successful API call",
      "should_trigger": false
    },
    {
      "query": "Our getting-started page takes too long - what's our time to first value?",
      "should_trigger": false
    },
    {
      "query": "Write a hello-world doc for the new SDK",
      "should_trigger": false
    },
    {
      "query": "Trim our onboarding docs to the minimum path to one verified success",
      "should_trigger": false
    },
    {
      "query": "How do we cut time-to-first-success from 20 minutes down to 5?",
      "should_trigger": false
    },
    {
      "query": "Our signup-to-first-API-call path has too many steps in it",
      "should_trigger": false
    },
    {
      "query": "Write the script for a screencast walking through our SDK",
      "should_trigger": false
    },
    {
      "query": "I need a two-column visual and narration beat sheet for a demo video",
      "should_trigger": false
    },
    {
      "query": "Write the narration for a video walkthrough of the dashboard",
      "should_trigger": false
    },
    {
      "query": "Storyboard a three-minute product demo video",
      "should_trigger": false
    },
    {
      "query": "Should we build a certification program for our platform?",
      "should_trigger": false
    },
    {
      "query": "Design a developer academy with learning paths and badges",
      "should_trigger": false
    },
    {
      "query": "Which tutorials should exist across our whole docs set?",
      "should_trigger": false
    },
    {
      "query": "Plan our developer education curriculum for next year",
      "should_trigger": false
    },
    {
      "query": "Audit our docs structure and classify every page against Diátaxis",
      "should_trigger": false
    },
    {
      "query": "Where does this page belong in our documentation information architecture?",
      "should_trigger": false
    },
    {
      "query": "Our docs navigation has drifted from the file tree - fix it",
      "should_trigger": false
    },
    {
      "query": "Turn our support tickets into error reference pages",
      "should_trigger": false
    },
    {
      "query": "Write troubleshooting pages people find by pasting the error string",
      "should_trigger": false
    },
    {
      "query": "Build an error-code catalog generated from one source of truth",
      "should_trigger": false
    },
    {
      "query": "Our code samples stopped compiling after the 3.0 release",
      "should_trigger": false
    },
    {
      "query": "Set up CI that tests every snippet in our documentation",
      "should_trigger": false
    },
    {
      "query": "Check snippet parity across our Python, Go and Node SDKs",
      "should_trigger": false
    },
    {
      "query": "Write the migration guide for our v2 to v3 breaking changes",
      "should_trigger": false
    },
    {
      "query": "We need an upgrade guide with a deprecation timeline and a codemod",
      "should_trigger": false
    },
    {
      "query": "Write a \"how we rewrote our ingestion pipeline in Rust\" post",
      "should_trigger": false
    },
    {
      "query": "Draft a public postmortem for last week's outage",
      "should_trigger": false
    },
    {
      "query": "Structure my accepted conference talk into a rehearsable outline",
      "should_trigger": false
    },
    {
      "query": "My talk runs eight minutes long - what do I cut?",
      "should_trigger": false
    },
    {
      "query": "Design a live demo that survives the stage if the wifi dies",
      "should_trigger": false
    },
    {
      "query": "I need a one-command reset for my demo environment",
      "should_trigger": false
    },
    {
      "query": "Review my repository README",
      "should_trigger": false
    },
    {
      "query": "Which badges should I keep on my README?",
      "should_trigger": false
    },
    {
      "query": "Write the getting-started section of our README",
      "should_trigger": false
    },
    {
      "query": "What do developers actually search for when they hit this error?",
      "should_trigger": false
    },
    {
      "query": "Our docs pages don't rank - fix the canonicals and hreflang",
      "should_trigger": false
    },
    {
      "query": "Write a CONTRIBUTING.md and set up good-first-issues",
      "should_trigger": false
    },
    {
      "query": "How do I get a stranger to their first merged pull request?",
      "should_trigger": false
    },
    {
      "query": "Write my CFP abstract for KubeCon",
      "should_trigger": false
    },
    {
      "query": "Write the release notes for version 4.2",
      "should_trigger": false
    },
    {
      "query": "Plan a quarter of developer content with owners and dates",
      "should_trigger": false
    },
    {
      "query": "Improve our in-app onboarding flow's activation rate",
      "should_trigger": false
    },
    {
      "query": "Walk me through this codebase so I understand the architecture",
      "should_trigger": false
    },
    {
      "query": "Generate documentation from the comments in this repo",
      "should_trigger": false
    },
    {
      "query": "Create a classroom course for my students learning Python",
      "should_trigger": false
    },
    {
      "query": "Teach me how React hooks work",
      "should_trigger": false
    },
    {
      "query": "Explain why our event loop blocks under load",
      "should_trigger": false
    },
    {
      "query": "Write an explanation page about how our consensus protocol works",
      "should_trigger": false
    },
    {
      "query": "Write the explanation page for why we chose eventual consistency",
      "should_trigger": false
    },
    {
      "query": "Document every endpoint of our REST API with request and response shapes",
      "should_trigger": false
    },
    {
      "query": "Write a how-to for rotating API keys in production",
      "should_trigger": false
    },
    {
      "query": "Write a how-to for deploying our agent on GKE with Terraform",
      "should_trigger": false
    },
    {
      "query": "Benchmark a competitor's docs and quickstart quality against ours",
      "should_trigger": false
    },
    {
      "query": "Build our devrel tracking plan and event taxonomy",
      "should_trigger": false
    },
    {
      "query": "How much of our devrel budget should go to education versus events?",
      "should_trigger": false
    },
    {
      "query": "Design the interview loop for a developer educator role",
      "should_trigger": false
    },
    {
      "query": "Make our docs readable by a coding agent running unattended",
      "should_trigger": false
    },
    {
      "query": "Design our engineering onboarding buddy system and 30-60-90 plan",
      "should_trigger": false
    }
  ]
}

# Published findings and self-set baselines

Every number and named rule this skill uses, split by whether someone published it or this skill set it. Read this before defending a threshold to a docs team, and before changing one.

## Contents

- Sourced rules - published by a named framework, template or study
- Self-set baselines - this skill's own defaults, safe to renegotiate
- Named frameworks and why each one fits
- Deliberately excluded

## Sourced rules

| Rule used in this skill                                                                                                                                                                                                  | Source                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| A tutorial is learning-oriented and serves the user _at study_; a how-to serves the user _at work_. Conflating them is "the single most common conflation made in software product documentation"                        | Diátaxis, diataxis.fr/tutorials-how-to                                                                                       |
| "The first rule of teaching is simply: don't try to teach."                                                                                                                                                              | Diátaxis, diataxis.fr/tutorials                                                                                              |
| "A tutorial is not the place for explanation." Explanation "distracts their attention from that, and blocks their learning."                                                                                             | same                                                                                                                         |
| "A tutorial must inspire confidence." "Your tutorial ought to be so well constructed that things can't go wrong, that your tutorial works for every user, every time."                                                   | same                                                                                                                         |
| "Repetition is not the best teacher - sometimes it's the only teacher."                                                                                                                                                  | same                                                                                                                         |
| Don't: abstraction and generalisation, explanation, choices, excess information                                                                                                                                          | same, verbatim don't-list                                                                                                    |
| Language patterns: "In this tutorial, we will…", "First, do x. Now, do y.", "The output should look something like…", "Notice that…", "You have built…"                                                                  | same                                                                                                                         |
| 15-60 minutes end to end                                                                                                                                                                                                 | Good Docs Project, `tutorial/tutorial-template-guide.md`: "Ideally, your tutorial should take 15 to 60 minutes to complete." |
| At most seven primary steps                                                                                                                                                                                              | same: "Avoid writing procedures that are more than seven primary steps long."                                                |
| At most four substeps per primary step                                                                                                                                                                                   | same: "Aim for no more than four substeps in any primary step."                                                              |
| Objectives phrased "By the end of this tutorial, you'll be able to…" + a verb, written before the content and used to decide scope                                                                                       | same; it points authors at Arizona State University's Learning Objectives Builder                                            |
| Overview declares learning objectives, intended audience, prerequisite knowledge                                                                                                                                         | same                                                                                                                         |
| Imperative verb headings expressed as a complete thought; no -ing form (harder to translate)                                                                                                                             | same                                                                                                                         |
| Orient the reader before the action - name the file or dialog first                                                                                                                                                      | same                                                                                                                         |
| Code samples carry required `import`/`using` statements and explanatory comments, and are verified to work                                                                                                               | same                                                                                                                         |
| Summary lists skills gained, worded differently from the objectives                                                                                                                                                      | same                                                                                                                         |
| The reader has ideally already completed a quickstart                                                                                                                                                                    | same                                                                                                                         |
| "What I explain or say is almost irrelevant, and the only thing that matters is what I get people to do, in order that they learn." Explanation and demonstration are "packaging for the lesson," not the lesson itself. | Daniele Procida (Diátaxis's creator), writing outside the framework itself, vurt.org/articles/on-teaching/                   |

## Learning-science sources

These justify the ladder and the fading table; none of them prescribes a number.

| Effect                    | Finding                                                                                                | Origin                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------- |
| Worked-example effect     | For a novice, studying a complete worked example beats solving unaided                                 | Sweller & Cooper, 1985            |
| Completion-problem effect | Partially completed problems perform as well as full solutions                                         | Paas, 1992                        |
| Guidance-fading effect    | Remove solution steps progressively as competence builds, continuously rather than in fixed stages     | Renkl and Atkinson                |
| Expertise-reversal effect | The example that helps a novice becomes redundant, then harmful, for an expert                         | Kalyuga et al., 2000-2001         |
| Split-attention effect    | Keep the explanation adjacent to the code it explains                                                  | cognitive load theory             |
| Desirable difficulty      | Difficulty that slows acquisition can raise long-term retention; retrieval strength ≠ storage strength | Robert A. Bjork, term coined 1994 |

Cite these effects as the origin of a principle, never as a measured effect size for documentation.

## Self-set baselines

These are this skill's own defaults - reasonable, untested, and meant to be agreed with the user rather than quoted as an industry bar.

| Baseline                    | Value                                                                      | Where it came from                                                                                                                               |
| --------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Checkpoint spacing          | Every 3-5 steps                                                            | A prescription in the `technical-tutorials` open-source skill, adopted because it divides a seven-step maximum sensibly. Self-set, not measured. |
| Pass threshold              | All six criteria hold on one cold run                                      | Assembled from the sourced rules above; the gate itself is self-set.                                                                             |
| Fading schedule             | Full example, then diff, then requirement, across early/middle/late thirds | Guidance fading is sourced; this particular three-stage split is not.                                                                            |
| Companion-branch CI cadence | Weekly, plus on commit                                                     | Chosen to catch product drift between releases. Pick the cadence that matches your release train instead.                                        |
| "Split it" trigger          | Measured runtime over 60 minutes                                           | The 60-minute ceiling is sourced; splitting rather than trimming is a judgement call.                                                            |
| Transfer-test delay         | Ten minutes after the last checkpoint                                      | Long enough that the last code block is not on screen. Arbitrary otherwise.                                                                      |

When you state one of these to a user, say it is a starting default. Presenting a self-set number as a standard is how a docs team ends up defending a figure nobody can source.

## What real organizations do at the same three points

None of the three baselines above matches a published practice at its stated granularity, but each sits near a real, citable one a team can compare itself against instead:

- **Checkpoint spacing.** Diátaxis argues for a checkpoint at every single step ("every step the learner follows should produce a comprehensible result"), tighter than this baseline. Google Codelabs, its own tutorial-authoring format, constrains total length rather than checkpoint interval: five to ten steps per codelab, split into two above that. freeCodeCamp's two-minute rule forces a passing-test checkpoint after nearly every step. None of the three publishes an "every 3-5 steps" rule.
- **Pass threshold.** No org publishes a tutorial-specific six-item gate, but each criterion has a named individual source outside this skill: output matching documented output is task success, a core usability-testing metric; a checkpoint passing without help echoes the unassisted-completion condition in historical software acceptance-test designs; zero prerequisites discovered after step 1 is the Good Docs Project's own "before you begin" promise, worded as avoiding a reader "getting halfway through a tutorial and discovering they don't have something needed"; and the unaided repeat on an untaught variation is far-transfer testing, a standard instructional-design evaluation method distinct from the near-transfer worked-example studies cited above.
- **Fading schedule.** Renkl and Atkinson's own experimental designs fade continuously rather than in three fixed stages: a complete example, then one solution step blanked, then more blanks added incrementally, until only the bare problem remains. The three-stage shape here is a coarser, more authorable version of a continuous effect, not the effect's own documented shape.

## Named frameworks and why each fits

- **Diátaxis** - the only framework that defines the tutorial _as an artefact type_ and separates it from the how-to. It supplies the reliability constraint the whole skill rests on.
- **The Good Docs Project tutorial template** - the only widely used template with hard structural limits, and the only source for the size numbers.
- **Backward design** (Wiggins & McTighe, _Understanding by Design_, 1998): three stages, in order - identify desired results, determine acceptable evidence, plan learning activities, matching this skill's own order of objective, then checkpoints and the transfer test, then steps. Naming it stops the common inversion, where the author writes the feature walkthrough first and reverse-engineers an objective. Documented criticism to respect: pre-set goals can underestimate learners, so treat the objective list as a floor.
- **Kirkpatrick's four levels** (1954; popularised 1959/1994) - reaction, learning, behaviour, results. The documented failure mode is the one tutorial authors have: teams get stuck at levels 1-2 and never measure behaviour. Completion rate maps to level 1, the transfer test to level 2, and downstream product use to level 3.
- **Cognitive load theory** - see the table above.

Frameworks deliberately _not_ invoked:

- Gagné's Nine Events - built for instructor-led sequences, not a page.
- ADDIE - a program lifecycle, so it belongs to a curriculum skill.
- The Socratic method - Diátaxis is explicit that a tutorial gives actions rather than interrogating the learner.

## Deliberately excluded

- Any completion-rate benchmark. The activation bands quoted in developer-marketing material are self-reported vendor numbers about signup funnels, not tutorials. Compare a tutorial against its own baseline instead.
- Any claim about how long a learner will tolerate a tutorial beyond the sourced 15-60 minute band.

# Tutorial outline template

Fill this skeleton in order. Anything that doesn't serve the learning objective gets deleted rather than shortened.

## Table of Contents

- [Size limits](#size-limits)
- [Skeleton](#skeleton)
- [What you'll build](#what-youll-build)
- [Background](#background)
- [Before you begin](#before-you-begin)
- [Step 1: <imperative verb phrase>](#step-1-imperative-verb-phrase)
- [Step 2: <imperative verb phrase>](#step-2-imperative-verb-phrase)
- [Checkpoint: <what is now true>](#checkpoint-what-is-now-true)
- [Step 5: <imperative verb phrase>](#step-5-imperative-verb-phrase)
- [What you built](#what-you-built)
- [Troubleshooting](#troubleshooting)
- [Where to go next](#where-to-go-next)
- [Section rules](#section-rules)

## Size limits

The first three come from the Good Docs Project's tutorial template guide and can be quoted as such; the readings after each dash are this skill's.

- 15-60 minutes end to end (sourced). Under 15, it's a quickstart; over 60, split it at a checkpoint into an ordered pair.
- At most seven primary steps (sourced: "avoid writing procedures that are more than seven primary steps long"). A ladder that needs more rungs is two tutorials.
- At most four substeps inside one primary step (sourced).
- One environment: one language, one package manager, one OS family, pinned versions - this skill's rule, following Diátaxis' ban on presenting choices.

## Skeleton

```markdown
# Build <artefact> with <technology>

<One sentence: what the learner will be able to do afterwards.>

|                       |                                      |
| --------------------- | ------------------------------------ |
| **Time**              | 30 minutes (measured, not estimated) |
| **Level**             | <declared audience level>            |
| **You'll need**       | <language/runtime + versions>        |
| **Assumed knowledge** | <concept> (link), <concept> (link)   |

## What you'll build

<Screenshot, sample output, or short description of the finished artefact.>

By the end of this tutorial, you'll be able to:

- <verb the learner performs>
- <verb the learner performs>

## Background

<At most a short paragraph: the feature being learned, or the layout of the starter project. The only place explanation is allowed. Delete it if the tutorial needs none.>

## Before you begin

| Requirement | Version | Check       |
| ----------- | ------- | ----------- |
| <tool>      | <min>   | `<command>` |

Assumed knowledge, with a link each:

- <concept> - <link>

## Step 1: <imperative verb phrase>

<One or two sentences of what and why. No theory.>

<One code block, in the shape the ladder calls for at this stage.>

Expected output:

<Separate block containing real output from a real run.>

## Step 2: <imperative verb phrase>

…

## Checkpoint: <what is now true>

<Command the learner runs.>

<Exact expected output.>

You've now <capability>. If the output differs, see <troubleshooting link> or reset to `<branch/tag/seed command>`.

<Optional> Try it yourself: <variation>. Answer: <link or collapsed block>.

## Step 5: <imperative verb phrase>

…

## What you built

<Complete final artefact, in one block or one linked file, so the learner can diff their work.>

You can now:

- <capability, worded differently from the objectives above>

## Troubleshooting

### <verbatim error message>

**Cause:** <one line.>
**Fix:** <command or edit.>

## Where to go next

- <How-to guide for the most common real-world variant>
- <Reference page for the machinery just used>
- <Explanation page for the why>
```

## Section rules

**Header table.** The time figure comes from a measured cold run, not from the author's estimate. The level line is a contract: it tells an expert to skip and a novice what to read first.

**What you'll build.** Show the end result before the first command. A learner who can picture the destination tolerates a longer path.

**Background.** The Good Docs Project template puts one context section between the overview and the prerequisites, and it is the single place a tutorial tolerates explanation. Use it for the feature under study or the shape of a provided starter project, and keep it to a paragraph - everything past that is the explanation Diátaxis says blocks learning.

**Before you begin.** Two lists, never one: software with a check command, and knowledge with a link. Knowledge prerequisites are what distinguishes a tutorial's preamble from a quickstart's - and omitting them is what makes learners feel stupid instead of unprepared.

**Steps.**

- Verb heading.
- One action.
- One block.
- Real output.
- A fail pointer where the step can realistically fail.

When the learner edits more than two files, show the file tree with the current file marked.

**Checkpoints.** Every 3-5 steps. Never a bare "it should work now" - a command, its exact output, and a way back.

**What you built.** Restate as capabilities the learner has, not topics the page covered. Give the complete artefact so they can find their own typo by diffing.

**Troubleshooting.** Headed by the verbatim error string, so search and Ctrl-F both find it. Two lines each: cause, fix. Anything longer belongs on a dedicated error page.

**Where to go next.** At most three links, one per Diátaxis quadrant. A wall of links at the end is an abandonment surface.

# Verification protocol

A tutorial is verified by watching a learner run it, not by reading it. The author's machine and the author's head both lie: one has the dependencies, the other has the answers.

## Choosing the runner

- Match the declared audience level. A senior engineer breezing through a beginner tutorial proves nothing - they patch the gaps unconsciously and report success.
- Never the author, and ideally not the author's team.
- Two runners beat one: a first-time evaluator and someone already fluent in the ecosystem hit different walls.
- Where the tutorial has an enterprise or internal-tooling audience, one runner must go through the real access request, not a pre-provisioned account.

## Environment

- Clean machine or fresh container: no cached credentials, no globally installed toolchain, no leftover project directory.
- The exact OS and runtime versions the tutorial declares - and one version newer, to see how loudly it breaks.
- Install from the published artefact (registry package, released image), not from the working tree. That is what the learner will have.

## Running it

1. Hand over the tutorial link and nothing else. No verbal setup, no "oh you'll also need…".
2. The runner narrates aloud; the observer stays silent and takes notes. Answering a question destroys the data point you came for.
3. Timestamp the start of each step and each checkpoint. The gap between two timestamps is the friction.
4. Record every hesitation, re-read, scroll-back and tab-switch away from the page - each one marks a place the text failed to carry the learner.
5. Let failures play out. The recovery path is part of the artefact under test.

## Log every event as one of four kinds

| Kind                | Meaning                                                         | Action                                                                 |
| ------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Defect              | A command failed, or output differed from the documented output | Fix before shipping. Non-negotiable.                                   |
| Hidden prerequisite | Something needed that wasn't in "Before you begin"              | Move it up; add a check command.                                       |
| Concept gap         | The learner did the step but couldn't say what it did           | The step introduced more than one idea, or explained none. Split it.   |
| Friction            | Hesitation, re-read, wrong guess that self-corrected            | Rewrite the sentence; usually an ambiguous pronoun or an unnamed file. |

Anything the runner "figured out" is a defect, not a success.

## The transfer test

Ten minutes after the last checkpoint, ask the runner to perform the objective once more on a variation you never demonstrated - a different field, a second endpoint, another event type. Give them the reference docs and no help.

- They do it → the skill transferred; the fading worked.
- They do it by scrolling back and adapting the last code block → partial; move the fade one or two steps earlier.
- They can't start → the tutorial was a long quickstart. Add a produce-it-yourself step before the final checkpoint.

This is the only check that distinguishes a tutorial from a page of copy-paste, and it is the one authors skip.

## Keeping it verified

Tutorials rot faster than quickstarts: more steps, more surface, more product drift.

- Keep a companion repository with one branch or tag per checkpoint, generated from the published steps rather than maintained by hand.
- Run a CI job per checkpoint branch: install the published package, run that checkpoint's command, assert the documented output.
- Schedule it (weekly is enough) as well as running it on commit. Tutorials break when the _product_ ships, not when the docs repo changes.
- Fail the docs build, not an advisory job - a red mark nobody owns gets muted within a month.
- Track the age of the last successful run per checkpoint, not the last edit date. An untouched tutorial that still passes is healthy; a recently edited one that hasn't run is not.

## Instrumentation to add before publishing

- A completion event fired at the final checkpoint, plus an event per checkpoint, so drop-off is per step rather than per page.
- Copy-button clicks per block: blocks nobody copies are usually blocks nobody reaches.
- Search and support queries quoting a step verbatim - the fastest signal that a sentence is ambiguous.
- Downstream: whether completers go on to perform the same task in the product within a week. Completion without downstream use means the tutorial taught the tutorial, not the product.

# Worked examples

Paired examples for the decisions authors get wrong most often: step shape, guidance fading, checkpoints, objective wording, and the shape of an audit hand-back.

## Table of Contents

- [1. Step shape](#1-step-shape)
- [2. Guidance fading](#2-guidance-fading)
- [3. Checkpoints](#3-checkpoints)
- [4. Objective wording](#4-objective-wording)
- [5. Audit hand-back](#5-audit-hand-back)

## 1. Step shape

### Bad

> ## Step 3: Set up the database
>
> Now configure your database connection. Depending on whether you're using Postgres or MySQL, install the appropriate driver and set your connection string. You may also want to configure a connection pool - see the configuration reference for the available options. Then run the migration.

Four defects:

- Two new concepts (driver, pooling).
- A branch the learner must resolve.
- No code.
- No observable output.

A learner who gets an error here cannot tell which decision caused it.

### Good

> ## Step 3: Connect to the database
>
> Create `db.js` with the connection:
>
> ```js
> import postgres from "postgres";
>
> export const sql = postgres("postgres://localhost:5432/tasks_tutorial");
> ```
>
> Check the connection:
>
> ```bash
> node -e "import('./db.js').then(({sql}) => sql\`select 1 as ok\`).then(console.log)"
> ```
>
> Expected output:
>
> ```
> Result(1) [ { ok: 1 } ]
> ```
>
> Connection refused? The database isn't running - see [Troubleshooting](#connection-refused).

One concept, one path, one command, real output, one fail branch. Pooling is a link in the next-steps section, not a decision on the critical path.

## 2. Guidance fading

The same tutorial at step 2, step 5 and step 8. What changes is how much the learner produces.

### Step 2 - full worked example

> Create `routes/tasks.js`:
>
> ```js
> import { Router } from "express";
> import { sql } from "../db.js";
>
> const router = Router();
>
> router.get("/", async (req, res) => {
>   const tasks = await sql`select * from tasks order by id`;
>   res.json(tasks);
> });
>
> export default router;
> ```

Complete, imports included, runs as pasted. A novice needs the whole thing - building it unaided at this stage costs attention the concept needs.

### Step 5 - diff-shaped, insertion point named

> In `routes/tasks.js`, add a filter above the existing handler:
>
> ```js
> // routes/tasks.js - add above router.get("/")
> const parseStatus = (value) =>
>   ["open", "done"].includes(value) ? value : null;
> ```
>
> Then use it inside the handler you wrote in step 2:
>
> ```js
> const status = parseStatus(req.query.status);
> const tasks = status
>   ? await sql`select * from tasks where status = ${status} order by id`
>   : await sql`select * from tasks order by id`;
> ```

The learner places the code themselves and reuses the shape they already know. The file is named and the insertion point is explicit, so placement is unambiguous without being automatic.

### Step 8 - requirement plus expected output

> Add pagination to the same endpoint. A request to `/tasks?limit=2&offset=2` should return the third and fourth tasks:
>
> ```json
> [
>   { "id": 3, "title": "Buy milk" },
>   { "id": 4, "title": "Call Ana" }
> ]
> ```
>
> Reject a `limit` above 100 with a 400. Stuck? [See one solution](#solution-pagination).

Same pattern the learner has now written twice, applied without a template. This is the step that produces criterion 5 of the pass threshold - the learner performing the skill unaided. Skipping it leaves them with a working app and nothing transferable.

### Negative example - no fading

Step 8 written like step 2, a full file to paste. It is faster to write, faster to complete, and teaches nothing: the learner never once produced the pattern.

## 3. Checkpoints

### Bad

> ## Checkpoint
>
> At this point everything should be working. If not, double-check the previous steps.

No command, no output, no recovery. "Double-check the previous steps" is what the learner was already going to do, and it is why they abandon here.

### Good

> ## Checkpoint: the API returns your tasks
>
> Start the server:
>
> ```bash
> npm start
> ```
>
> In a second terminal:
>
> ```bash
> curl -s localhost:3000/tasks
> ```
>
> Expected output:
>
> ```json
> [{ "id": 1, "title": "Write tutorial", "status": "open" }]
> ```
>
> You now have a running API reading from your own database.
>
> Empty array? The seed didn't run - `npm run seed`, then retry.
> Want to start fresh here tomorrow? `git checkout step-4` in the companion repo.
>
> **Optional:** before running the next step, predict what `curl -s "localhost:3000/tasks?status=done"` returns today. [Answer](#checkpoint-4-answer).

Verifiable state, a stated capability, two recovery routes, and an optional retrieval-practice prompt with the answer available - difficulty placed after the checkpoint passes, never on the critical path.

## 4. Objective wording

| Weak                      | Strong                                                           |
| ------------------------- | ---------------------------------------------------------------- |
| Understand authentication | Protect an endpoint so unauthenticated requests get a 401        |
| Learn about our SDK       | Stream a model response into a terminal UI with the SDK          |
| Explore webhooks          | Receive a webhook, verify its signature, and reject a forged one |
| Understand pagination     | Add server-side pagination to a REST endpoint                    |

The strong column is testable: at the end you can ask the learner to do it on a variation and see whether they can. The weak column can only be asked about, never demonstrated - which is why tutorials written from it drift into feature tours.

## 5. Audit hand-back

The request was "nobody finishes our webhooks tutorial".

### Bad

> I read through the tutorial. Overall it's solid but a bit long, and the tone could be friendlier. Step 4 is probably where people get lost - the signature verification part is complex and could use more explanation. I'd also suggest adding screenshots and breaking up the longer paragraphs. Happy to draft a revision.

Nothing here is falsifiable. "Probably where people get lost" is a guess from reading, which is exactly the input the verification protocol exists to replace, and "more explanation" pushes the page toward the one thing Diátaxis says blocks learning. An author can act on none of it without redoing the diagnosis themselves.

### Good

> Two cold runs, both matching the declared level (backend engineers, no prior use of the product). Both stopped inside step 4. Ordered by learners blocked:
>
> | Step | Event               | What happened                                                                                                                                                         | Fix                                                                                            |
> | ---- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
> | 4    | Defect              | `verify(payload, sig)` documented as returning a boolean; the published SDK 3.x returns an object. Both runners hit a false negative and assumed their key was wrong. | Regenerate the block from a real run against 3.x; add the return shape to the expected output. |
> | 2    | Hidden prerequisite | Tunnelling tool never mentioned; both runners stalled ~6 min before finding one.                                                                                      | Add to "Before you begin" with a check command.                                                |
> | 4    | Concept gap         | Both completed the step and neither could say what the signature protected against. Step 4 introduces the header, the secret and the comparison at once.              | Split into 4a (read the header) and 4b (compare the digest), one output each.                  |
> | 6    | Friction            | "Add the handler to your app" - no file named. Both scrolled back to step 2 to guess.                                                                                 | Name the file and the insertion point.                                                         |
>
> Not defects: the missing screenshots, the paragraph length. Neither runner hesitated at either.
>
> Rewriting steps 2 and 4 first covers both blocked runs. Sending the revision back through one more cold run before publishing.

Every row is an observation with an owner, and the last block matters as much as the table: it stops the author from spending the rewrite on cosmetics nobody stumbled over.

---
name: developer-tutorial
description: Writes or audits a teaching tutorial for a developer product - one new concept per step, checkpoints the learner can verify and resume from, guidance that fades, troubleshooting hooks, and a demonstrable skill at the end. Use whenever the user mentions a tutorial, a build-along or hands-on guide, a "learn X by building Y" article, a workshop or lab handout, a developer course lesson, or says nobody finishes their tutorial - even if they just say "write a guide that teaches this". Do NOT use for a zero-to-first-success quickstart (samber/developer-relations-skills@developer-quickstart-guide) or a video script (samber/developer-relations-skills@technical-video-script).
license: MIT
metadata:
  author: Samuel Berthe
  version: "1.0.1"
---

# Developer Tutorial

You are a developer-education specialist. You produce one artefact: a tutorial that takes a learner who cannot yet do something and leaves them able to do it, having built a working thing with their own hands along the way.

A tutorial is not a quickstart. A quickstart proves the product works; a tutorial builds a skill the learner keeps. Spend the extra time that buys on teaching, never on options, theory, or feature tours.

Every number in this skill is one of two kinds, classified in `references/published-findings.md`:

- **Sourced** numbers come from Diátaxis or the Good Docs Project tutorial template. Quote them as such.
- **Baseline** numbers are this skill's own defaults, published by nobody. Offer them as a starting point and let the user move them.

## Scope check

Confirm the task is really a tutorial before starting. Route elsewhere when:

- The goal is one fast proof that the product works, with no skill transfer → quickstart skill.
- The reader already has the skill and wants to accomplish a specific real-world task, with branches for their situation → how-to guide skill. Say so out loud instead of absorbing the request. Diátaxis calls conflating the two "the single most common conflation" in software product documentation. A how-to forks on the reader's situation, and every fork you import destroys the tutorial's single guaranteed path.
- The artefact describes the machinery endpoint by endpoint → API reference skill.
- The artefact argues a position or tells an engineering story → engineering blog skill.
- The artefact is spoken and recorded → video script skill.
- The question is which tutorials should exist, or whether to build a course or certification → education-strategy skill.

See the References section for the exact skill identifiers.

## Interview

Ask one question at a time, multiple-choice whenever you can offer options. Stop as soon as you can state the learning objective and the audience level. Infer the rest and confirm it later.

**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 should the learner be able to _do_ afterwards that they cannot do now? Push for a demonstrable capability, not a topic.
2. What will they build while learning it? Offer 2-3 candidate artefacts and let them pick the smallest one that still requires the concept.
3. What is the audience level: never used this product, used it once via the quickstart, or experienced with it but new to this area?
4. What can you assume they already know (language, framework, protocol, domain concepts)? Everything else has to be taught, linked, or removed.
5. Which single environment does the tutorial run in (language, package manager, OS, versions)?
6. How long should it take? The Good Docs Project's stated range for the format is 15 to 60 minutes. Past that, split it.
7. Is there a companion repository, starter project or sandbox, or does the learner start from an empty directory?
8. Is this greenfield, or an audit of a tutorial that people abandon?
9. Who can run the finished tutorial end to end as a learner, and on what machine?
10. What date must the page be live by? A hard date stops the ladder one rung earlier and defers every metric past the drop-off view.
11. One-off win (a launch needs a page next week) or compounding asset (the docs set builds on this for two years)? Compounding promotes the robustness rung, the companion repo and CI-run checkpoints. One-off deletes all three.
12. What is the authoring ceiling in hours, and who owns this page every release? No named owner deletes the polish rung and the companion repo outright.

Both rankings below (the ladder's stop rung and the KPI order) are defaults, not laws. Re-rank them against these answers, and against what you already know about this team: an existing analytics pipeline makes the drop-off view near-free, an existing sandbox makes the real-data rung near-free, and either promotion beats the default order.

## Workflow

The step order is deliberate: objective (step 2), then evidence (step 3), then activities (steps 4-7). Reversing it is the standard failure - an author who drafts the walkthrough first and writes an objective afterwards ships a feature tour with a learning-shaped title, because the steps were chosen by what the product does, not by what the learner needs. This ordering has a name: backward design (Wiggins & McTighe, _Understanding by Design_); use the name when a team pushes back.

1. **Set the mode.** For an audit, have someone run the existing tutorial cold first (step 11) and collect real abandonment points - never rewrite from reading alone. For greenfield, go to step 2.
2. **Write the learning objective as a sentence starting with a verb the learner performs**, before drafting any content, and use it to decide what is out of scope. The Good Docs Project's phrasing is "By the end of this tutorial, you'll be able to…" followed by a verb such as _design_, _assess_ or _develop_. If you can't test whether they can do it, it isn't an objective. See [./references/worked-examples.md](./references/worked-examples.md) for weak/strong phrasing pairs.
3. **Decide how you will know they got there**: the final checkpoint, and the variation you will ask them to do unaided in step 11. Do this before drafting a single step; it is what stops the ladder from drifting into a tour.
4. **Pick the artefact they build.** The smallest thing that cannot be built without the concept. A bigger project adds typing, not learning.
5. **Declare the audience level and prerequisites explicitly** at the top: required software with a check command per row, and required knowledge with a link per item. A tutorial written for two levels at once serves neither - the expertise-reversal effect says the same worked example that carries a novice becomes redundant, then actively harmful, for an expert.
6. **Build the concept ladder** (see below). One new concept per step, ordered by dependency, everything else reused. Pick the stop rung there, against the ranking in that section.
7. **Draft the steps.** Give each step an imperative-verb heading stated as a complete thought ("Connect to the database", not "Connect") and exactly one action. Orient first when the learner must open a file or screen. Include the code in the shape the ladder calls for, the expected output from a real run, and a one-line pointer to the troubleshooting entry wherever the step can fail.
8. **Place checkpoints** every 3-5 steps (baseline), each one a verifiable state and a resume point (see below).
9. **Write the ending.** State what the learner can now do, and give the complete final artefact in one place. Then point to the next quadrant:
   - How-to guides, for real variants.
   - Reference, for the machinery.
   - Explanation, for the why.
10. **Run a humanizer pass** on the prose (never on code blocks) with your preferred humanizer skill, so it reads like an engineer teaching rather than a model narrating.
11. **Verify against the pass threshold** below, with a real learner who matches the declared level. Fix and rerun until it passes.
12. **Instrument and record.** Define the completion event and the per-checkpoint drop-off view. If your environment has persistent memory, store the learning objective, audience level, chosen environment and the concepts deliberately left out, so sibling tutorials stay consistent instead of contradicting this one.

## Concept ladder

Order concepts by what depends on what, not by how the product is architected. Run each layer end to end before adding the next:

| Layer        | Adds                                        | Learner sees                   | Costs you every release                                                    |
| ------------ | ------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------- |
| Skeleton     | Minimum code that runs                      | Something responds             | Near-zero: it breaks only when the install command does                    |
| Core concept | The capability the tutorial is about        | The promised behaviour         | An hour per breaking change, and you would pay it anyway                   |
| Real data    | Their own input instead of hardcoded values | Their data flowing through     | Fixtures, a seed script and a sandbox that drift whenever the schema moves |
| Robustness   | Error handling, validation                  | A failure handled deliberately | One error path and its expected output; stable across releases             |
| Polish       | Config, tests, structure                    | Production shape               | A standing job: config, lockfiles and a test suite that rot on their own   |

Row order is the build order (each layer needs the one under it), so it is not the ranking. The ranking decides where you stop, since skeleton and core concept are not optional: without them the objective is unmet.

- value: core concept > real data > robustness > polish
- authoring plus upkeep effort: polish > real data > robustness > core concept > skeleton
- efficiency: core concept > robustness > real data > polish

Robustness outranks real data on efficiency while losing to it on value: one deliberate failure path is written in an hour and survives every release, where real data drags fixtures and a sandbox that break on the next schema change. **Default stop: core concept plus robustness.** Move up to real data when the learner's own input is what the objective names, or when a sandbox already exists and the rung is therefore near-free.

That order starves polish - production shape is what a reader eventually needs and what costs the most to hold. Promote it anyway when the tutorial doubles as onboarding onto an internal or enterprise tool, where the production shape _is_ the objective. When the interview named no owner for the page, delete the polish rung from the plan rather than parking it at the bottom: an unowned rung reappears as scope and then rots.

Two rules keep the ladder teaching instead of dictating.

**One new thing per step.** When a step introduces two unfamiliar ideas and the result is wrong, the learner cannot tell which half broke and blames themselves rather than the page.

**Fade the guidance.** Early steps hand over the full worked example, later steps hand over less, until the learner is producing code (see the stage table below). A tutorial that copy-pastes as much at step 7 as at step 1 taught nothing: the learner has a working app and no transferable skill.

| Stage  | Block shape                                                            |
| ------ | ---------------------------------------------------------------------- |
| Early  | Full file, all imports, runs as pasted                                 |
| Middle | Only the added lines, in a named file, with the insertion point stated |
| Late   | The requirement plus the expected output; the answer one click away    |

Guidance fading is a named cognitive-load result (Renkl and colleagues); the three-stage split above is this skill's own baseline shape for it, not part of the finding.

"One click away" never means one blob of finished code. Grade the reveal instead, so a learner who is nearly there gets the smallest push that unblocks them:

1. A pointer to the relevant reference page.
2. Pseudocode.
3. The solution with the interesting lines blanked out.
4. The full solution.

That numbering is the escalation the learner walks, not the order you write them in. When you can only author some of the rungs, rank by value per authoring hour: `blanked solution > pointer > full solution > pseudocode`.

- The blanked block is the full solution minus three lines, and teaches the most.
- The pointer is a link.
- The full solution is free to paste, and teaches the least.
- Pseudocode is prose you rewrite on every API change to say what the blanked block already says.

Rung 3 works because of the completion-problem effect (Paas, 1992): a partly filled block teaches as well as a complete one and costs the learner more thought. Use the cognitive-load effects named in this section to justify a shape, never to derive a number.

Everything competing for the learner's attention is subtracted from the concept: an unexplained flag, a second package manager, a renamed variable, a stray warning. Pre-supply boilerplate through a starter repository or a scaffolding command - typing it teaches nothing.

## Checkpoints

A checkpoint lets the learner confirm the system is in the state you claim, without trusting their own reading. Three parts, always:

1. A command or action producing observable output.
2. The exact expected output.
3. A recovery route when it doesn't match - the troubleshooting entry, or a restorable snapshot of the correct state.

A checkpoint also does a job a quickstart's expected-output line never has to. A tutorial is long enough to be abandoned and resumed, so make every checkpoint a **resume point** - a branch or tag in the companion repository, an idempotent seed script, or a documented "reset to step N". A learner returning tomorrow re-enters at their last passed checkpoint instead of restarting.

A companion repository whose branches drift from the published steps is worse than no repository; learners trust the code over the prose and land in a state the text never describes.

## Language and reliability

Diátaxis states the constraint bluntly: "A tutorial must inspire confidence", and it "ought to be so well constructed that things can't go wrong, that your tutorial works for every user, every time". One step that fails costs more than three that succeed earn - the learner concludes they are not smart enough and leaves.

- Write "In this tutorial, we will…", then "First, do x. Now, do y." First-person plural for the journey, imperative for the actions.
- Set the expectation before the result: "The output should look something like…".
- Direct attention that would otherwise be missed: "Notice that…", "Remember that…".
- Affirm at the end: "You have built…".
- Offer no choices and no alternatives. A branch the learner must resolve before they understand the product is a stall.
- Keep explanation to a sentence and link out. Explanation is the hardest temptation to resist and the fastest way to lose a learner mid-build. Procida makes the same discipline concrete outside the Diátaxis framework itself: "what I explain or say is almost irrelevant, and the only thing that matters is what I get people to do, in order that they learn," a rule he traces to a class of teenagers who learned CSS faster by doing than by being told.
- Repeat a pattern across steps deliberately. Diátaxis puts it as "repetition is not the best teacher - sometimes it's the only teacher"; it looks redundant only to the author.
- Never write a recovery line as a verdict. "You should have set the secret first" tells a stuck learner they failed; name the state instead: "if the secret isn't set, this returns 401; set it and retry."

Desirable difficulty (Bjork's term: difficulty that slows acquisition but builds retention) and Diátaxis' zero-friction rule sound contradictory. They are not, because they govern different parts of the page. The main path (environment, commands, the code the learner types) is governed by reliability, and every failure there is your defect.

The concepts the learner must retain can carry deliberate difficulty, but only as optional, clearly marked additions after a passed checkpoint, with the answer available:

- Predict an output before running it.
- Break something on purpose and read the error.
- Extend the feature by one parameter.

Difficulty created by omission or ambiguity is not desirable difficulty. The learner absorbs it as their own failure and leaves.

## Audience-context split

The artefact is the same for every reader: same objective, same ladder, same checkpoints. Two things shift with who arrives.

**Individual learner, self-serve product.** They can abandon at any second and owe you nothing.

- Front-load the visible result.
- Keep the whole path inside the free tier.
- Never let a billing prompt land before the last checkpoint.

**Team member onboarding onto an internal or enterprise tool.** They cannot abandon, so the failure mode is silent misunderstanding rather than a closed tab.

- Name the access they need and who grants it, before step 1.
- Give an offline or on-prem variant of every command that assumes internet.
- Add checkpoints they can show a reviewer.

## Pass threshold

Nobody publishes an acceptance gate for tutorials, so this six-criterion gate is a baseline - say so when you propose it, and let the user cut or add criteria before you measure against it. Only criterion 4's 15-60 minute band is sourced (the Good Docs Project's stated range).

The tutorial ships when someone who matches the declared audience level runs it end to end on a clean machine and all six hold:

1. Every step's real output matches the documented output.
2. Every checkpoint passes without help from the author.
3. Zero prerequisites - software or knowledge - are discovered after step 1.
4. Elapsed time lands inside the stated estimate, and inside 15-60 minutes overall.
5. The learner can perform the objective once more, unaided, on a variation you did not walk them through.
6. Every abandonment or hesitation is traced to a specific step and fixed, not averaged away.

Criterion 5 is the one that separates a tutorial from a long quickstart. When it fails, the ladder faded too late or not at all - the learner copied their way to a working app.

## KPIs

Kirkpatrick's four levels sort these, and name the trap: training teams measure levels 1-2 and stop, so a tutorial with a strong completion rate and no behaviour change looks like a success for years.

Rows run in instrument-first order (value per hour of wiring, not by level):

| Metric                                                                     | Level       | Wiring it costs                                                                                        | Reading it                                                                                                                         |
| -------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Transfer-test pass rate from the cold runs                                 | 2 Learning  | Near-zero - criterion 5 of the pass threshold already runs it; you only record the result              | The only in-tutorial evidence that a skill formed rather than an app getting pasted together                                       |
| Per-checkpoint drop-off                                                    | 1 Reaction  | An hour: one event per checkpoint, and the checkpoints already exist                                   | One dominant abandonment checkpoint marks a broken step, not a hard concept - fix that step before rewriting the concept around it |
| Support questions or issues quoting a specific step                        | 2 Learning  | Near-zero to collect, a standing job to read                                                           | Each one localises a wrong or ambiguous instruction to a sentence you can fix                                                      |
| Completion rate (reached final checkpoint / started)                       | 1 Reaction  | Free once the drop-off events exist                                                                    | Whether the page holds attention; it says nothing about whether anyone learned                                                     |
| Median completion time vs. the stated estimate                             | 1 Reaction  | Free once the drop-off events exist                                                                    | A stated 30 minutes that measures 70 breaks the page's first promise; re-measure, then restate                                     |
| Share of completers who perform the same task in the product within a week | 3 Behaviour | A standing job: the learning surface and the product must share an identity, decided before publishing | Completion without in-product repetition means the tutorial taught the tutorial, not the product                                   |

- value: behaviour share > transfer-test > per-checkpoint drop-off > support questions > completion rate == median time
- wiring effort: behaviour share > support questions > per-checkpoint drop-off > completion rate == median time > transfer-test
- efficiency: transfer-test > per-checkpoint drop-off > support questions > completion rate == median time > behaviour share

Completion rate and median time tie on both axes for one reason: they are two readings of the same start-and-finish event pair, so neither can be bought without the other and neither localises a defect. **Default: instrument the first two and read the third.** Add the rest when the page has run one full cohort.

That order starves the behaviour share - the highest-value metric on the table and the only one that shows the product changed. Promote it above everything anyway when the tutorial is counted as an activation step, or when someone asks the page to justify its own headcount. No cheaper metric answers that question, and the identity plumbing has to land before publishing or the first cohort is unmeasurable.

Set no numeric target from outside: there is no trustworthy published completion benchmark for developer tutorials, so compare each figure against this tutorial's own previous version.

Guard against rot by running each checkpoint's companion branch in CI against the published package, on a schedule as well as on commit. Tutorials break when the product changes, not when the docs repo changes.

## Invocations and what you return

Identify which of three shapes you were given before answering. The wrong deliverable is the most expensive mistake here, because it looks finished.

| The user says                                                       | Mode       | You return                                                                       |
| ------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------- |
| "Write a tutorial teaching people to stream responses from our SDK" | Greenfield | The interview, then the drafted page against the outline template                |
| "Nobody finishes our webhooks tutorial, fix it"                     | Audit      | A prioritised defect list keyed to steps, then the rewrite of the failing ones   |
| "Is this a tutorial or a how-to?"                                   | Scope call | The classification, the reason, and the sibling skill that owns the other answer |

**Greenfield.** Follow `references/tutorial-outline-template.md` section by section and hand back a complete page. Never ship a page whose expected-output blocks are placeholders - an unrun output block is the defect this whole skill exists to prevent. If you cannot run the commands, say which blocks are unverified and hand the author a run list.

**Audit.** Return a table, not prose: step number, what breaks, which of the four event kinds it is (defect, hidden prerequisite, concept gap, friction - see `references/verification-protocol.md`), and the fix. Order rows by how many learners the step blocks, not by page order.

**Either mode:** pin down the objective and the audience level before starting. Guessing them is what produces the feature tour.

## Failure modes

| Symptom                                                                   | Fix                                                                                                      |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Opens with architecture or theory before the first action                 | Cut to the first action; link the concept doc                                                            |
| A step introduces two new concepts at once                                | Split it; each half gets its own observable output                                                       |
| Learner still copy-pastes at the last step                                | Fade earlier: switch to diff blocks, then to requirements                                                |
| Tutorial branches on OS, framework or package manager                     | Pick one; link the variants; keep the branch out of the path                                             |
| Checkpoint says "you should see something like this" with no exact output | Paste the real output from a real run                                                                    |
| Companion repo branches don't match the steps                             | Regenerate branches from the published steps; test each in CI                                            |
| It runs 90 minutes                                                        | Split at a checkpoint into two tutorials with a stated order                                             |
| Everyone stops at the same step                                           | Instrument it, rerun that step cold, fix the step - not the prose around it                              |
| Feature tour disguised as a tutorial                                      | Return to the objective; delete every step that doesn't serve it                                         |
| Written for beginners and experts simultaneously                          | Pick a level, declare it, and link the other audience elsewhere                                          |
| Troubleshooting entries written as "you should have…"                     | Rewrite blame-shaped wording; a stuck learner reads it as a verdict on themselves and closes the tab     |
| A threshold from this skill quoted to the team as an industry standard    | Check `references/published-findings.md` before quoting; most of the numbers here are self-set baselines |

## References

- See [./references/tutorial-outline-template.md](./references/tutorial-outline-template.md) for the page skeleton and section-by-section rules.
- See [./references/worked-examples.md](./references/worked-examples.md) for good/bad pairs on steps, fading, checkpoints and audit output.
- See [./references/verification-protocol.md](./references/verification-protocol.md) for the learner-run test protocol and the CI job that keeps checkpoints alive.
- See [./references/published-findings.md](./references/published-findings.md) for which rule came from where, and which numbers are this skill's own baselines.
- See samber/developer-relations-skills@docs-code-sample-standards for sample policy, testing, and per-language parity.
- See samber/developer-relations-skills@developer-troubleshooting-docs for the error pages your steps link to.
- See samber/developer-relations-skills@developer-docs-structure-audit for where a tutorial belongs among how-to, reference and explanation.
- See samber/developer-relations-skills@developer-education-strategy for curricula, courses and certification.
- See samber/developer-relations-skills@engineering-blog-post for a narrative post about how something was built, instead of a step-by-step tutorial.
- See samber/developer-relations-skills@developer-how-to-guide for the goal-oriented how-to a competent reader needs, instead of a tutorial.