Crafting Code Examples That Actually Teach

Good technical writing hinges on good examples, yet there's surprisingly little guidance on how to construct them. The most reliable approach is counterintuitive: instead of inventing examples from scratch, start with real code you've written, then strip away the irrelevant details until a self-contained illustration remains.

Why Realistic Examples Matter

Consider a typical attempt to explain Python lambdas using map to square a list of numbers. It demonstrates the syntax, but it fails twice as a teaching tool:

  • Mapping a squaring operation over a list is rarely something you'd do in production code (unless you're solving Project Euler problems).
  • The pattern isn't idiomatic Python—even in that scenario, a list comprehension like [x*x for x in numbers] would be the natural choice.

A better, still simple example uses lambdas with sort:

children = [{"name": "ashwin", "age": 12}, {"name": "radhika", "age": 3}]
sorted_children = sorted(children, key=lambda x: x['age'])

Yet that example remains contrived—why would anyone need to sort children by age? The disconnect between the example and real workflows weakens the lesson.

From Real Code to Minimal Example

The cure for contrivance is to start with actual code. A quick grep through existing Python projects for sort.+key reveals a pattern immediately:

  • tasks.sort(key=lambda task: task['completed_time'])
  • emails = reversed(sorted(emails, key=lambda x:x['receivedAt']))
  • sorted_keysizes = sorted(scores.keys(), key=scores.get)
  • shows = sorted(dates[date], key=lambda x: x['time']['performanceTime'])

Most real-world sorting is by time. That observation yields a clean, relevant example—sorting calendar events by Unix timestamp:

events = [
    { 'date': 1625837042, 'name': 'birthday party'},
    { 'date': 1620581136, 'name': 'dinner with Yifei'},
    { 'date': 1589045136, 'name': 'dentist appointment'},
]
sorted_events = sorted(events, key=lambda x: x['date'])

This example is just as simple as sorting children by age, but it carries far more weight. Realistic examples do double duty: they teach the syntax and convince the reader the concept is worth adopting. Showing someone a task they can imagine doing—ideally one they've done before—makes the value of lambdas tangible.

The Hidden Cost of Simplicity

Distilling a real-world problem into a standalone example is often painfully slow. One recent case study: a CSS bug that occupied hundreds of lines of JavaScript and stylesheets took two hours to isolate and reduce to a minimal demonstration of five lines of HTML plus a sliver of CSS. The final result doesn't look like it took hours to produce, and that's precisely the point—the distillation process is invisible in the output.

That time investment is justified. When hundreds of readers will work through an example, a few hours spent making it minimal and clear saves each of them significant time untangling irrelevant complexity.

Two Distinct Example Types

Beyond realism, there's room for variety in example selection:

  • Surprising examples that challenge a reader's mental model and teach through the shock of unexpected behavior.
  • Drop-in examples that readers can copy, paste, and adapt directly as a starting point for their own code.

Both serve different pedagogical purposes, but both benefit from the same grounding in code that someone actually wrote and shipped.