Personal productivity, cooking

How to Make Recipes Easier to Follow Using Mermaid Text (Really)

I’ll demonstrate using a delicious lasagne recipe

You know what I hate most about following recipes? The important information is buried in blocks of text, so it’s easy to overlook. Who hasn’t missed a step and ruined what would have been great food?

It doesn’t matter if the text blocks are numbered, or if they have pretty pictures of ingredients arranged around them. That’s just distracting.

What I want to know is:

• What do I use?
• When do I use it?
• What sequence of actions do I follow?

All that should be up front and central so that I can concentrate on bringing the delicious.

Extracting information from blocks of text isn’t a new problem. System designers have been grappling with it since the days of mainframes. One tool they used to understand what was going on was a sequence diagram.

Keep calm. You don’t need to be a system designer to use them. Here’s an example.

Alice and John are having a rather dull conversation, but forget their dying relationship! Look at the diagram. It clearly shows the participants, what they’re saying, and the sequence they’re saying it in.

I think recipes should be like that, and there’s a way to achieve that easily and for free. It’s called Mermaid text, and it’s MarkDown for diagrams.

You type something like the text below, and a mermaid editor will draw it for you:

Alice->>John: Hello John, how are you?
Alice->>John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
John-->>-Alice: I feel great!

In fact, that’s how I created that diagram.

Time-out! Sit up straight and say out loud, “sequence diagram”. Say it again and wait for a moment. Did the devil appear? Did anyone attack you?

No, I didn’t think so.

We’re going to turn a lasagne recipe into a sequence diagram, and we will be proud because making fresh lasagne will be easier.

Making sequence diagrams so easy even politicians could use them

Here’s the plan. Read through a recipe and make notes using Mermaid notation. Copy and paste the notes into a (free) Mermaid editor, and a really useful, clear sequence diagram (not the devil) will appear.

I found a lasagne recipe on the BBC website and tried the technique out. I thought it worked really well, but you’ll be the judge of that…

All you need to know about mermaids

Mermaid notation is powerful, but we only need a subset to analyse lasagne recipes. You can find full details here:

Here’s what you need to follow this article.

Mermaid diagram descriptions are text files, and you can create them in any editor you like. You then copy and paste the description to any tool that supports Mermaid text (see later).

The first line indicates the diagram type:

sequenceDiagram

In a sequence diagram, participants (e.g., Alice and John) send messages to each other. You show that with a text arrow and some label text.

Alice->>John: John, can you hear me?

Alice sends a message to John, “John, can you hear me?” The colon indicates the start of the message.

Every so often, you want sequences of messages to happen more than once. Here’s how you do that:

loop until divorced 
	Alice->>John: John, can you hear me?
end

Whatever is after the word, loop, is the label for the loop.

You can add notes to a sequence by doing this:

note over John: He gets duller by the minute.

If you want to break up text in a comment into separate lines, use “
”.

Well, that’s it, but where do you get a free Mermaid editor? Glad you asked.

Free online Mermaid diagram tool

You can find a free Mermaid editor at:

Type that URL into your web browser of choice, and this is what you’ll see.

You type your instructions into the left-hand panel, and the diagram on the right updates.

Tap/click on PNG button and the diagram fills the screen. You could print it out or save it locally. Both work.

I’ll tell you about an app for Apple devices later.

Turning a recipe into a sequence diagram

The Internet boasts many lasagne recipes, but I decided to follow one on the BBC website.

I’ll follow each step of this recipe and translate it into a Mermaid description. It’s about 18 or so lines, and it took me ten minutes to do.

I used a text editor to create the description, and copied and pasted it one line at a time into the Mermaid editor. This also made it easy to try out on the Mermaid editor app on my iPad.

How did I approach it? I looked out at each step and picked out ingredients and equipment as participants. What I did with the ingredients and equipment became the messages.

Building the diagram

Go to the Mermaid editor at https://mermaid.live. If it isn’t displaying a sequence diagram, tap/click on sample diagrams and select sequence diagram.

Clear the default text and type in sequenceDiagram, then return.

Step 1

To make the meat sauce, heat 2 tbsp olive oil in a frying pan and cook 750g lean beef mince in two batches for about 10 mins until browned all over.

— BBC Lasagne Recipe

I translated that into:

olive0il->>pan: heat 2 tbsp
beef->>pan: cook 2 batches of 750g for 10min or until brown.

Step 2

Finely chop 4 slices of prosciutto from a 90g pack, then stir through the meat mixture.

— BBC Lasagne Recipe

I translated that into:

prosciutto->>pan: finely chop and stir through meat

Step 3

Pour over 800g passata or half our basic tomato sauce recipe and 200ml hot beef stock. Add a little grated nutmeg, then season.

— BBC Lasagne Recipe

I translated that into:

passato->>pan: pour 800g
beefStock->>pan: add 200ml
nutMeg->>pan: add a little grated nutmeg and season

Step 4

Bring up to the boil, then simmer for 30 mins until the sauce looks rich.

— BBC Lasagne Recipe

I translated that into:

note over pan: bring to boil and simmer for 30 mins

Step 5

Heat oven to 180C/fan/160C/gas 4 and lightly oil an ovenproof dish (about 30 x 20 cm).

— BBC Lasagne Recipe

I translated that into:

note over pan: heat oven to 180C
note over pan: lightly oil dish

Step 6

Spoon one third of the meat sauce into the dish, then cover with some fresh lasagne sheets from a 300g pack. Drizzle over roughly 130g ready-made or homemade white sauce.

— BBC Lasagne Recipe

I translated that into:

pan->>dish: spoon third of meat sauce <br> cover with fresh lasagne sheet <br> drizzle 130g of white sauce

Step 7

Repeat until you have 3 layers of pasta. Cover with the remaining 390g white sauce, making sure you can’t see any pasta poking through.

— BBC Lasagne Recipe

I translated that into:

loop until there are three layers
end

I then moved step 6 into the loop to get:

loop until there are three layers
    pan->>dish: spoon third of meat sauce <br> cover with fresh lasagne sheet <br> drizzle 130g of white sauce
end

Step 8

Scatter 125g torn mozzarella over the top.

— BBC Lasagne Recipe

I translated that into:

note over dish: scatter 125g of mozzarella over top

Step 9

Arrange the rest of the prosciutto on top. Bake for 45 mins until the top is bubbling and lightly browned.

— BBC Lasagne Recipe

I translated that into:

note over dish: arrange rest of prosciutto on <br> and bake for 45 mins until top is bubbling

The Result

Tap on “PNG”, and the browser window fills with your lasagne sequence diagram.

What have you gained?

• You can clearly see what’s needed for the recipe.
• When to add ingredients is unambiguous.
• You know when you’re finished with utensils and ingredients.

Here’s the complete description. You could copy and paste it into a Mermaid Editor in one go, if you prefer.

sequenceDiagram
olive0il->>pan: heat 2 tbsp
beef->>pan: cook 2 batches of 750g for 10min or until brown.

prosciutto->>pan: finely chop and stir through meat

passato->>pan: pour 800g
beefStock->>pan: add 200ml
nutMeg->>pan: add a little grated nutmeg and season

note over pan: bring to boil and simmer for 30 mins

note over pan: heat oven to 180C
note over pan: lightly oil dish

pan->>dish: spoon third of meat sauce <br> cover with fresh lasagne sheet <br> drizzle 130g of white sauce

loop until there are three layers
    pan->>dish: spoon third of meat sauce <br> cover with fresh lasagne sheet <br> drizzle 130g of white sauce
end

note over dish: scatter 125g of mozzarella over top

note over dish: arrange rest of prosciutto on <br> and bake for 45 mins until top is bubbling

iOS/iPadOS Mermaid Diagram Editor

If (like me) you prefer your apps to run on your device, and you’re an iPad user, you could use MermaidEditor. It cost me £3.49, and I have no links to the developers.

I copied and pasted the lasagne recipe description into the app, and this is what I got.

Why’s this great?

Translating a recipe into Mermaid text forces you to think clearly about what you’re doing, and, once you understand, those insights are readily available to you in the future.

This isn’t limited to food preparation. Sequence diagrams are useful for anything complex where you need to understand what has to be done and when. It could be a recipe or buying a house. Lasagne taste better, so I went with that.