Some Ranting About Examples

Delayed newsletter next week

I'm doing the Alloy workshop on Monday and will have zero energy after that, so the newsletter will be out by Tuesday at the earliest. I'm spending most of this week putting the final touches on the workshop, so no office hours or follow-up newsletter either.

(Also I just signed up to volunteer as a street medic. I reserve the right to say "hey I'm spending today patching people up instead of writing about computer things" for the next few weeks.)

Some thoughts on examples

I've thought more about examples than most people about there. Not just like coming up with new examples, but thinking about the theory of examples. What it means to have an example, what makes an example good, the purposes of presenting examples in the first place. Here are a couple thoughts in no particular order:

Purposes of examples

Existential

Examples that prove that a category is nonempty. If I ask you for an example of a false statement, the statement "all integers are positive" is an existential example. It demonstrates that there is such a thing as false statements. Existential examples don't give us any information about the structure of the category, or how big it actually is, but shows it exists. If someone cannot give you an existential example, then their claim is meaningless.

Existential examples can be anti-persuasive and convince people that the broader category does not have more than a few members. This is my gripe about "famous women in CS": everybody gives the example of Grace Hopper, which makes it seem like Grace Hopper is the only famous woman in CS. When in reality there are a lot more.

Instructive

Instructive examples teach you how to do something. If I wanted to show you how to write a Python function, I could write something like

def foo(bar, baz=False):
  if baz:
    return bar + 2
  return bar + 1

And you could take that, copy it over, and modify it for your use case. Notice how boring it is. I'm not trying to inspire you to use Python functions and not trying to show you about how to use them best. I'm just showing you how to use them. When teaching, we use a huge number of instructive examples.

It's not necessary for an instructive example to be interesting, and in fact there is a trade-off here. Interesting examples require more specificity in them, which a beginner can confuse as necessary syntax. I included an optional value in that function, and a beginner might think that all Python functions need an optional value. Not being clear on what's essential to the idea versus specific to that particular example is a big problem in teaching. On the other hand, people internalize ideas faster when examples are interesting. There is a good essay in Making Software about teaching concurrency: people who learned concurrency in the context of reserving tickets at a concert picked it up faster than people who learned it in the context of threading.

A problem I see is that there is a trade-off here, but people don't realize there's a trade-off. In fact people don't realize that instructive examples are distinct from other kinds. They use instructive examples when they really need persuasive ones.

Persuasive

A persuasive example is one that's designed to get you to change your opinions or behavior through the act of studying the example. Most often this looks like getting you to try something that you wouldn't have tried otherwise. Most of my examples on formal methods aim to be persuasive examples: they try to convince people that formal methods could help them with their job. A subset of persuasive examples is motivating examples: those that try to interest somebody in what they're learning. I'd say that primarily persuasive examples are aimed at outsiders while motivating examples are aimed at learners.

Writing a good persuasive example is very hard. There are many failure modes here: snake oil, controlled demos, misunderstanding the audience, "word problems", etc. I wrote a bunch more about persuasive examples here and word problems later in the essay.

Insight-building

Examples designed to teach something through the use of studying the example. I see the difference between this and instructive as being about helping people improve their mental model versus just helping a person improve their information or rote skill. So something like

def f(l=[]):
  l.append(3)
  return l

(f(), f()) == ([3, 3], [3, 3])

That helps people understand how Python represents default values and functions. I haven't dived as deep into insight-building examples as instructive and persuasive, and I think there's a lot here that nobody's really researched.

Case Study

Example that's real world and messy. The messiness is important, as it shows how to bridge the gap between the abstraction and reality. These examples are also topics unto themselves, which is why people don't use them as much as they should. Shame really, they're great and do a lot to help people master a topic. But they're also very hard to write. Practical TLA+ ended with a couple of case studies and they took a long time for me to come up with, write, and polish. Still super proud of them and think they're the capstone of the book.

A rant about word problems

I don't know if this is something other countries deal with, but in the United States, math is often taught with "word problems". These are exercises that try to show how to extract the underlying mathematical problem from a day-to-day issue and also to persuade skeptical students that math is actually fun and useful. Something like "Bella goes to the hardware store and buys two gallons of paint for $112, including a $80 painting charge. How much does the paint cost?" (ref)

Word problems are almost universally terrible. This is the same problem as the instructive example trade-off. The above feels artificial because nobody can actually imagine being in a situation where they have to figure out how much paint cost based on a final charge. In order to actually represent a real-world problem that someone might actually use math in, you have to provide a lot of domain detail. I can create a practical real-world problem but it would require me explaining a lot of background as to why the problem is the way it is. To take a math problem I actually had to solve recently:

"I use the following ingredients in a chocolate filling:

I use this to make 100 chocolates. If each chocolate weighs 9 g, the outer shell is also milk chocolate, and the filling is evenly distributed among every single chocolate, how many calories is each chocolate?"

That's a place where mathematics is very practical. But then I have to explain things like unit conversions and why all of my serving sizes are different and how to go from overall mass to mass-per-chocolate and all sorts of fiddly bits like that. Important stuff the domain model, but actually distracting from learning math. Maybe a better example would be something like "this recipe calls for 40 g of butter and 200 g of flour, but I only have 30 g of butter and decide to scale the recipe down. How much flour do I need?"

It's likely the problem is that the people writing these problems have to come up with hundreds per math book, so really can't spend a lot of time making sure that each example is actually good. But I've also heard other math teachers complain that they can never find good word problems so maybe there isn't even a market for good word problems at all. I dunno.

Man, I'm finding it harder to concentrate right now than I thought I could manage, so I'm probably gonna cut off example rambling here. Gonna write more exercises and then head to bed. Be safe out there.

If you're reading this on the web, you can subscribe here. Updates are once a week. My main website is here.

My new book, Logic for Programmers, is now in early access! Get it here.