Document precise quantities

Peter Hilton

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

Coleslaw presents an opportunity and a challenge. You can make it easily at home, using cheap fresh ingredients, and get a better cheaper result than pre-made coleslaw. However, even a small cabbage yields more coleslaw than you can eat in a day, and you deserve freshly-made salad, even if you don’t cook for six people. To resolve this challenge, first learn to balance the ingredients.

Balancing ingredients

A typical British coleslaw recipe has four ingredients:

1. carrot
2. cabbage
3. onion
4. mayonnaise (or a fancier dressing).

To prepare the coleslaw, you finely chop or grate the ingredients (except for the mayonnaise), and mix them. You don’t cook a salad, so this has more in common with mixing a cocktail than most kinds of cooking. And like a cocktail, you have to get the proportions right, to balance the ingredients’ flavours.

If you already knew this, you only need one thing from a coleslaw recipe: the proportions. Coleslaw recipes: you have one job!

The coleslaw problem

Our typical British coleslaw recipe lists the main ingredients (excluding dressing) like this:

1 small white cabbage or ½ large
4 carrots
1 large red onion

Unfortunately, the International System of Units doesn’t include small cabbage, carrot, or large onion. This matters, because vegetable sizes vary by a factor of two (or more) in practice. For example, how many small (round) cabbages can I get out of this pointed white cabbage?

Which one of these counts as 1 carrot?

The coleslaw problem therefore boils down to this:

Coleslaw recipes suck, so you end up with too much carrot, in too much coleslaw

To solve this, the recipe writer and the recipe consumer (the cook) require additional hardware.

The coleslaw solution

The obvious solution to the coleslaw problem introduces measurements. To make one portion of coleslaw, mix the following ingredients:

• 30g cabbage, shredded
• 10g carrot, grated
• 5g onion, finely chopped
• 15g mayonnaise

These measurements set baseline proportions, which you can of course change. A fancier ingredient list would specify acceptable ranges for carrot, onion and dressing quantities, for 30 grams of cabbage. They also set a baseline portion size that helps prevent spending a week trying to use up half a kilo of coleslaw. Conveniently, coleslaw preparation scales down to a single portion, so it works even if you don’t need to feed a family of six.

Precise documentation

The coleslaw recipe problem illustrates several technical documentation failures, which take the form of three implicit lies:

1. ‘you’ll find it easy’ (if you already know how to do this)
2. ‘the proportions don’t matter’ (they do matter)
3. ‘I use whatever I have’ (I judge the proportions by eye, having done this before)

Exact quantities may seem overly precise, but a representative starting point has more value than indicating how much room for flexibility the instructions have. Exploring that flexibility will happen anyway.

Cookbook recipes generally provide poor examples of technical writing problems, but in this case coleslaw’s simplicity emphasises the lesson. Even something this basic requires precision, at least to start with, to remove guesswork from your first attempt.