01 The problem
The cost isn’t embarrassment. It’s operational.
Non-technical project managers sit in meetings where integration failures are discussed in language they can’t parse. An engineer says the vendor’s endpoint is throwing 500s and asks whether to back off the retry logic. The PM nods.
- Slow escalation. A vague ticket — “the integration is broken” — generates a round trip of clarifying questions before anyone can begin diagnosis.
- Misassigned blame. Without knowing what a status code indicates, PMs escalate a rate limit to the vendor as an outage, or spend hours debugging something only the vendor can fix.
- Lost credibility. The PM becomes someone engineering routes around rather than through.
Existing training on this topic is written for people learning to build integrations. That’s the wrong performance objective. These learners will never write a request. They need to diagnose, interpret and escalate.
02 The audience
Experienced professionals with one specific gap
Project managers, implementation managers and client-facing staff on technical teams. No coding background and no intention of acquiring one. Time-pressured, and skeptical of training that wastes it.
Two design constraints followed directly.
They won’t tolerate being taught to code
Any screen that looked like a programming tutorial would lose them. The module never shows a line of code.
They’re not novices at their own job
Talking down to them would be worse than not training them at all. The scenario puts them in a role they already occupy, making decisions they already recognize.
03 The design
Four decisions that shaped the build
Terminal objective Given a failing integration, gather the right diagnostic information, interpret what an engineer reports, and communicate accurately to both engineering and the client.
Assessment is judgment, not recall
The obvious version of this course ends with a quiz: what does 429 mean? But knowing the definition isn’t the performance gap. The gap is choosing correctly under time pressure with incomplete information. So the assessment is a three-decision scenario, and there is no scored quiz anywhere in the module. A learner can define every status code and still fail the scenario — which is the correct outcome, because that learner would also fail in the actual meeting.
Every wrong answer is a defensible one
None of the distractors are obviously stupid. Each is something a competent PM would genuinely do:
- Escalate immediately to the vendor — reasonable, but you can’t yet describe the problem
- Fix it properly rather than patching — good engineering instinct, wrong under a Friday deadline
- Promise the stakeholder an answer within the hour — good client management, but you don’t know the scope yet
Every option, correct or not, returns feedback explaining what would follow from that choice. That feedback is what carries the branching logic. The learner experiences consequence, not correction.
One concept, three encounters
429 Too Many Requests appears three times across the module, in escalating form: as
one entry in a status-code table; as a scaling failure that appears at rollout and never in the
pilot; and as a live diagnosis, where three of sixty sites are failing and all three are the
largest. The learner meets the same idea as vocabulary, then as pattern, then as decision.
Distributed practice on one concept, rather than single exposure to four.
Analogy before terminology
Lesson one opens with a waiter, not a definition. You don’t walk into the kitchen; you order from a menu; food comes back. The waiter is the API, the order is the request, the plate is the response, the menu is the documentation. The analogy pays off later without extra scaffolding — ordering something that isn’t on the menu is a 400-series error. Cross-industry examples follow immediately, so learners in any sector recognize the pattern before the module narrows to a specific rollout.
04 The build
The tool didn’t have the block the design needed
Authored in Articulate Rise. The build surfaced one significant constraint: Rise’s Scenario block wasn’t available on this plan. The branching interaction the design called for didn’t exist as a native component.
Rather than redesign around the tool’s limits, I rebuilt the interaction from available parts. Text blocks carry the narrative between decision points; multiple-choice knowledge checks carry the decisions themselves, with distinct feedback authored for every option rather than just the correct one.
The tradeoff The result isn’t visually branching. But the learner still makes a choice and receives a consequence specific to that choice, which is the pedagogical function branching serves. The constraint cost presentation, not instruction.
Three other build decisions worth naming:
- A custom status-code infographic replaced a text-heavy accordion. Color-coded families are scannable in a way a list of definitions isn’t.
- A three-tier escalation comparison rather than the usual before-and-after. The middle tier — an escalation that’s almost right, missing only the timestamp and the exact error — reflects the real failure mode more honestly than a strawman. Most PMs don’t send nothing useful; they send something incomplete.
- Flashcards for the three diagnostic questions, matching the module’s closing takeaway word for word, so the same three questions appear as practice and as summary.
05 The result
Built and shipped. No learner data yet.
The module is built, published and hosted independently at speaking-api-celona.netlify.app. It runs 15–20 minutes across four lessons, with two formative knowledge checks and a three-decision assessment scenario.
Stated plainly It has not been deployed to a learner population, so there is no completion or performance data. What this piece demonstrates is design reasoning: scenario over quiz, feedback as consequence, distributed practice on a single high-value concept, and a working solution to a real tooling constraint.
The evaluation plan, if deployed, would be straightforward — measure the quality of escalation tickets before and after. Do they name the specific function, include a timestamp, quote the exact error and define scope? That’s an observable behavior change, which is the level worth measuring. Whether learners can define a 429 is not.
06 What I’d change
Three, including one I caught too late
The status-code sequence runs long
Four consecutive blocks in lesson two cover the same territory — reference table, infographic, callout, scaling example. Each adds something, but a learner in a hurry feels it. A version two would fold the reference table into the infographic.
500s are underweighted relative to the assessment
The knowledge check closing lesson two tests 500-series errors, but the module’s emphasis is heavily on 429. That’s an alignment gap — assess what you emphasized — and I caught it late enough that the fix was a second callout rather than a restructure.
No audio narration
A version with narration would serve learners who prefer it, and would be a more complete demonstration of production capability.