Document acceptable substitutions

Peter Hilton

1. Failure & recovery
2. Specific techniques
3. Substitutions ←
4. Roles
5. Small tasks

Cookbooks annoy me by only including one recipe for each dish, instead of all of them. And despite various attempts at the definitive Wikipedia for recipes, none of them have pulled it off, although wikiHow comes close.

Tim Toady

Years ago, as a junior programmer, I discovered that programming languages usually embrace a specific idiom and style. I also learned that embracing these constraints, whether they arose accidentally, historically or by design, reduces friction.

The Perl programming language, however, chooses friction. Its community slogan that there’s more than one way to do it, abbreviated as TMTOWTDI (pronounced Tim Toady), challenged me to accept the kind of variation in code style that I wouldn’t even notice in, say, cooking.

Egg fried rice

I often cook egg fried rice for lunch, while working from home (photos, above). In ten minutes, I can cook tasty hot (and spicy) food with a flexible choice of vegetables. I also like that it works both with and without meat.

Around the time I first encountered Perl, I wrote my first egg fried rice recipe. It included prawns, chicken, ham, egg, peas, sweetcorn, spring onion, vegetable oil, and MSG. In the recipe, which I rarely cooked exactly the same way twice, I quipped that:

All of the ingredients are optional, except for the rice.

But I didn’t get that quite right. What you can leave out depends on what you’ve already got.

Substitutions

When I cook egg fried rice, I aim to have at least one ingredient in each of five groups:

1. ginger, garlic, shallot, spring onion (white part), onion
2. egg, pork (ham, bacon or roast pork), prawns, chicken
3. peas, sweetcorn, carrot
4. MSG, salt, soy sauce
5. spring onion (green part), unsweetened chilli sauce, sesame oil, crispy chilli oil

I prefer the highlighted ingredients, and only use the others as substitutes for whatever I’ve run out of. For example, Uncle Roger calls shallots better version of onion. Similarly, I prefer the lower-salt taste of MSG (historically avoided by white people due to decades-old racist myths).

Egg fried rice improves if you use as much of groups 2 and 3 as possible. This differs to most dishes, which become less interesting if you add more ingredients, and Long Island Iced Tea’s exception to the corresponding rule of thumb of 3–4 cocktail ingredients.

Cookbooks

Cookbooks systematically over-specify recipes, by failing to indicate how much freedom you have to change quantities or substitute ingredients. Perhaps we shouldn’t expect recipes to document more than one specific version of a dish – a snapshot among variations.

Too many cookbooks place the writer’s personal taste and situation above the reader’s. Telling me to use galangal instead of fresh ginger doesn’t help me much if I don’t know where to buy it. Sorry, Uncle Roger.

Software documentation

Mature software typically has some flexibility about where and how you use it. With the first version, you have to set it up in a certain way, on a certain platform. Later versions give customers more choice, so that more customers can choose it.

Technical documentation benefits from the same improvement, over time. The first version inevitably over-specifies, but as with the Perl and fried rice, the option to choose between more than one way lets you use the ingredients you have to hand. And tastes vary.