How We Teach

About · Philosophy

Most technical education fails at the moment it claims confidence. A course promises to teach you security, systems design, or machine learning, then presents a world where problems have neat solutions and expert consensus exists where it doesn't. The student leaves feeling either that they've mastered something (and they haven't — they've just memorized what they were told) or that they're too dumb to understand (and they're not — the material just lied).

Good technical teaching does something harder: it builds understanding by being honest about what's solved and what isn't, and it structures that honesty so each concept lands at the right level of depth. That's what Upshard aims for.

Start with the principle, not the thing

Every explanation should begin with why something works, not what it does.

“Prompt injection works because a language model processes its system prompt and any text it reads as one continuous token stream, with no built-in mechanism to distinguish trusted instructions from untrusted content.” That's the principle. Everything else descends from it.

The wrong version: “Prompt injection is when an attacker tricks a model into following their instructions.” You've named the thing, but you've taught nothing. A reader still doesn't understand why it works, so they can't predict when they're vulnerable.

Once the principle lands, then you build — direct vs. indirect, why the distinction matters, what mitigates it. The principle is the load-bearing beam. Everything else hangs from it.

Separate the attack surface from the defense

Many lessons blur these together: “Here's a vulnerability and here's how to fix it.” That's pedagogically backwards. It forces the reader to hold two ideas at once when they should be holding one.

Better: teach the attack surface as its own complete idea. Then, separately, teach what defenses look like against that surface. Better yet, acknowledge that the defenses don't fully work — because they usually don't.

“Guardrails catch the overwhelming majority of casual abuse cheaply. They also don't make bypass impossible, which is why you need robustness trained into the model itself.” That honesty is not discouraging. It's clarifying. It tells a developer what they're actually buying and what they still have to worry about.

Give the realistic threat model, not the academic best case

A lesson on adversarial examples could say: “An attacker needs white-box access to the model's weights and gradients.” That's true for the earliest attacks. It's also useless, because real systems don't expose weights.

Better: “Attacking a model you can only query for its final predicted label is harder, but it's realistic. HopSkipJumpAttack does it by iteratively walking a point toward the boundary while repeatedly querying the model.” Now a red teamer knows what's actually possible against a production API.

The difference between the academic version and the operational version matters. Most technical writing skips this translation. It shouldn't.

Name what's still unsolved

This is the move that separates teaching from marketing.

“Most published defenses against adversarial examples have been broken by a slightly stronger, adaptive attacker. That's why ‘robust’ in this literature means ‘not yet broken by a known attack,’ not ‘provably unbreakable.’ When you read a robustness claim, ask what attacker the claim was actually tested against.”

That sounds like bad news. It's actually the best news a technical reader can get, because it's true. It tells them not to trust the wrong thing. It builds intellectual honesty into their decision-making from the start.

Build the roadmap into the lesson

Each concept exists in relation to others. A lesson that pretends it's an island sets the reader adrift.

“This lesson is deliberately the shallow, naming pass. Later groups in this roadmap go deep on the OWASP categories we're touching today — you're getting the map now so you know where to look as we build out.” That's not just structure. That's permission to not understand everything yet. It's also a promise that the deeper material is coming.

Reference earlier lessons that built to this one. Point forward to what comes next. Show the reader where they are in the larger structure.

Use specific examples, not abstractions

“A resume containing white text on white background, invisible to a human reviewer but present in the file itself” teaches adversarial thinking better than “input channel” ever will.

“A hiring manager never sees it. The model reading the document sees it clearly, because to the model it's just more text in its input.” That's the insight. That's the bit that changes how a developer thinks about indirect injection.

Specific examples aren't decorative. They're where understanding actually lives.

Let the structure do the teaching

If you have to explain your structure, your structure isn't working.

Good structures are invisible. A lesson on guardrails that moves from “what is a guardrail” to “classifier vs. rails engine” to “why guardrails don't fully solve it” teaches through architecture, not through signposting.

The structure should be: principle → realistic threat model → limitations → what actually mitigates. Repeat that enough times and the reader internalizes that pattern. They start thinking like an engineer because you've shown them the skeleton of how engineers actually think.

Acknowledge your sources

If your lesson rests on a research paper or a practitioner's work, cite it and tell the reader what it actually found, not what a secondary source said it found.

“Nicholas Carlini's systematic evaluation of defenses found that the overwhelming majority fail once evaluated against an adaptive attacker.” That's specific. That's auditable. If a reader wants to go deeper, they have a real source.

Most technical writing drops references without context, as if naming a paper is the same as explaining it. It isn't.

Two passes minimum

The first pass is thinking. The second pass is clarity.

After writing something, read it cold. Every place where you had to re-read a sentence, rewrite it. Every place where you named something instead of explaining it, explain it. Every place where you hedged because you weren't sure, either become sure or name the uncertainty directly.

This is what separates a lesson from a draft. It's also what separates teaching from telling.


Every Upshard lesson is built on these principles. They're not decorative — they're how we ensure that reading a lesson changes how you think, not just what you know.

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark