What coding tutorials and teachers get wrong

Yesterday we were chatting about teaching and learning complex technical skills with an engineer I'm mentoring. She's a former chef.

She ranted about online recipes and how terrible they are, I ranted about coding tutorials and how terrible they are.

Same complaint: Recipes, tutorials, and many teachers skip the most the one useful piece of info after ingredients.

They don't answer How is this supposed to feel? What am I looking for?.

The best recipe has checkpoints

She's been looking at bread recipes lately. Trying to figure out the world's perfect sourdough, I think.

A lot of the recipes she finds say "Okay now proof for 2 to 12 hours" ... that's a huge range. How are you to know when it's ready? Does it depend on temperature? Humidity? Air pressure? The exact yeast bacteria you caught in your sourdough starter?

It depends on all those.

I don't know when sourdough is ready to bake. No idea what to look for. But I do know that after 7 years of trying I made the perfect potica for last year and it was thanks to combining several recipes, years of trial & error, and one fantastic recipe.

The potica recipe is Slovenian, you likely won't be able to read it. But take a look. Notice how every step comes with a photo.

That photo is crucial. Tells you what you're supposed to get.

Descriptions even say "If it's sticky, do this. If it's dry, do that". This is important because ingredients you get in USA are different than Slovenia. You have to adapt the recipe as you go.

Plus the dough works different, if your kitchen is cold. I learned that because California doesn't believe in insulation 🙃

The best teacher says why

Learning how to cook from my mom was messy and confusing. We started in 4th grade.

"You take a bit of this, simmer until it looks like that, then add this other thing, stir a but, sprinkle the spice, add this, if it looks wrong add a bit of that, oh now it's wrong the other way so add a pinch of blah"

Mom, I don't know what that means! Just tell me what to do.

"I can't tell you what to do dear. It's different every time."

And you know what? My mom was a genius. As frustrating as it was, she was right.

It IS different every time. Even my chef friend said that changing kitchens was like how come I don't know how to make steak anymore? The grill was different 🥲

A smöl rule to improve your teaching and learning

When teaching and learning I follow this rule:

If teaching, explain how you made a decision. The decision almost doesn't matter. What did you look for? How did you decide? What factors did you consider?

If learning, ‌ask how a decision was made. They made a suggestion, ask why. Why is this a better name for a function? Why does this code go in this file not that one? Why did you make a new component here but not there?

Practice in code review. Add an explanation every time you make a suggestion. If you can't explain it, skip the suggestion. You're full of shit 😉

But if you do explain it, next time they won't need your suggestion. That's teaching.

Cheers,
~Swizec