Document failure and recovery

Shubham Dhage

I’ve heard it said that cookbooks’ owners cook 1.5 recipes from each one, on average. I feel seen, and not only by the cookbooks on the shelf in the kitchen, but also reassured. Besides, cookbooks do sell well.

Perhaps we should accept that people buy cookbooks as safe gift choices, or because they look nice on the shelf, but that feels wrong. I like to imagine that a broader understanding of customer needs could resolve this cookbook disappointment.

Yorkshire puddings

Aged sixteen, I worked in a local carvery restaurant’s kitchen, in Southern England. The restaurant filled up on Sundays for traditional Sunday lunches of roast beef, turkey and ham. As untrained weekend staff, I only did the easy things in the kitchen: washing up, and preparing simple dishes.

One day, the chef showed a few of us how to make Yorkshire puddings:

1. break a tray of 30 eggs into a bucket
2. stir in flour, until the mixture reaches a certain thick consistency
3. stir in milk, until the mixture reaches a certain thin consistency
4. bake in a hot oven, in oil-lined Yorkshire pudding tins.

This approach assumes that you do this often enough to recognise the correct mixture consistencies without having to take the time to measure the flour and milk. However, getting that right requires practice, and correcting the mixture when you get it wrong.

Troubleshooting

After showing us how to make the mixture, the chef baked three test batches to show us the results of three ways to get the mixture wrong:

1. not enough egg
2. not enough flour
3. not enough milk.

Starting with a test batch, and recognising each of these failure modes, meant that we could learn how to get the mixture right. If we didn’t know how to troubleshoot the recipe, we would only know if the results looked good, in the same way that you compare what you’ve cooked to a photo in a cookbook.

Cookbooks

Conventional cookbooks don’t systematically help readers troubleshoot recipes. Instead, their recipes seem designed for people who already know how to cook the dish in question. Perhaps they only remind experienced cooks which quantities to use, or suggest variations on recipes they already know.

Fundamentally, cookbooks don’t teach you how to cook. But they could. Imagine a cookbook that followed each recipe with:

1. what often goes wrong
2. how you recognise what went wrong, and
3. how to fix it.

This explains why everyone finds it easier to learn to cook something for the first time from online video. Despite the lack of explicit troubleshooting, at least you can see what successful preparation looks like, and where your failed attempt deviated from the happy path.

Documentation complexity

User manuals often share cookbooks’ flaws, unhelpfully describing success. After all, I didn’t start reading the documentation because I couldn’t figure out that I can use the shape tool to add shapes to the canvas, for example.

Unfortunately, documenting mistakes, failure cases and error scenarios requires a lot more effort than merely describing how things work (when they work), because each one typically has a dozen ways to fail. But when it comes to manuals, cookbooks and otherwise, documenting failure serves our actual needs.