I’ve followed your instructions and I still can’t bake croissants

February 1, 2011 – 11:18 pm

This is a (rough) transcript of my lightning talk for FUDCon Tempe. For those looking for more resources, capsule my talk was based on the Dreyfus Model of Skill Acquisition, here and the best freely available (though not open-licensed) online resource I’ve found for quickly understanding and applying it it is this chapter (pdf) from the book Pragmatic Thinking and Learning.

Hi! I’m Mel. When I’m not doing Free Software and Open Source stuff, rehabilitation I’m a learning psychology geek. One of the questions I get asked a lot by fellow FOSS hackers is: Mel! Why don’t people help me with my project?

Based on a CC-BY-3.0 photo by assbach.

Before I can respond, they quickly say:

  1. But I have documentation!
  2. And I don’t bite on IRC!
  3. Really!

So I look at the documentation, watch them talk with folks on IRC, and go “all right, I see what your problem is.”

Now, instead of explaining this for software – I’ve been told that I make terrible analogies, so I’m going to talk about croissants.

Croissant CC-BY-2.0 by Alanna Risse

I’m learning how to bake. I’m a terrible baker. I touch an oven and something blows up. So I’m very much a novice in the baking world. Let’s say I want to learn how to bake bread, and I come across a recipe that looks like this.


  • flour
  • butter
  • stuff

bake it!

ask me if you have questions!

Aaaaand I promptly go “bwuuuuh?” and ignore everything. I mean, what the heck is a croissant?

It might help if you let me know that it’s a type of bread.

croissant-madrid CC-BY-3.0 by Tamorlan

Croissants: they’re really tasty bread

  • flour
  • butter
  • stuff

bake it!

ask me if you have questions!

Right! Bread! The thing I’m trying to learn to bake! I actually want to make this stuff now!

I’m still not sure exactly how I do that, though. What’s that list? How do I “bake it”? Nobody told me, so I went out and got groceries and tried putting it all in a bowl and now I… oh, shoot. You’re telling me I needed to get an oven beforehand? And preheat it? What… what does that mean?

Have I done something terribly wrong?

Should I give up and go away now?

based on cornetti1 CC-BY-SA-3.0 by exeair

Croissants: they’re really tasty bread

Makes approximately 20 croissants – the whole process takes about 6 hours, but most of that is for letting the dough rise.

Ingredients – buy these and have them out and measured on your table before baking.

  • 500g all-purpose flour
  • 340g unsalted butter, softened
  • <similarly coherent ingredients list>

You’ll need access to an oven for this recipe. Preheat your oven to 475°F before beginning.

bake it! Bake croissants on your oven’s middle rack for 3 minutes; then bring the heat down to 400°F and bake for 10-13 minutes or until the croissants are a light golden brown.

ask me if you have questions! Here are a few common questions and tips, along with pictures of the final product as baked by several people. If these don’t answer your question, I can be found <here>.


Now, most of us would think this recipe is still not written very well. That’s because we’re mostly novices in baking-land – we need clear step-by-step instructions to follow, we can’t just improvise through because we don’t know how these ingredients are going to interact with each other, we’ve never made croissants before so we can’t visualize the process without help – that sort of thing. We don’t have context.

And yet we think that wiki pages like this should be understandable by all human beings:

Download these tarballs, compile them, and everything should work.

They’re understandable to us – most of the time when we write docs like that, we’re experts. We’ve done this all before, we know what to expect, and rough notes are sufficient for us to reproduce our past results.

It’s been 5 minutes and Ian’s waving to tell me I’m out of time, so – moral of the story is, if you’re wondering why people don’t follow your instructions to help you with your project, go hit your local library and check out a cookbook. Bake something you’ve never baked before. Then, while eating it, open your documentation again and take a look at it with this in mind.

I’d be remiss to not include an actual recipe for croissants, so here’s a nice one (open-licensed, of course) – the WikiHow guide to croissant-making, which even includes a video tutorial. Nommmmm.

Know someone who'd appreciate this post?
  • Print
  • Facebook
  • Twitter
  • Google Bookmarks
  • email
  • Identi.ca
  1. 12 Responses to “I’ve followed your instructions and I still can’t bake croissants”

  2. The Sebastian approves too. OMNOMNOM. :)

    By Sebastian on Feb 1, 2011

  3. The Donald liked your lightning talk.

    By Donald on Feb 2, 2011

  4. Nice post, Mel. Tasty analogy.

    By Bryan Wilcox on Feb 2, 2011

  5. Nicely done, not a terrible analogy at all, more like a tasty one.

    Recipes can be a good suggestion if you get the right cookbook. Some are better written than others and some are actually written for pros and can be confusing.

    For those of you who want a more structured approach to instruction writing, try this…


    For techies who are non-cooks but want to be cooks I suggest Alton Brown’s “I’m Just Here for the Food” and “I’m Just Here for More Food”

    (note to Mel, “More Food” is specifically for Baking”)

    and/or Jeff Potter’s “Cooking for Geeks”

    SJ, who teaches, cooks and writes but gave up coding a while ago :-)

    By Stephen Jacobs on Feb 2, 2011

  6. screw the awesome documentation lesson, I’ve been looking for a really good croissant recipe for YEARS! thanks mel.

    By Adam Williamson on Feb 3, 2011

  7. In addition to my “me too!” response above, I thought that this talk was one of the gems amongst the presentations at FUDCon 2011.

    After being thrown off a bit when Mel started talking about croissants, I started realizing that this is how I learned linux: I’d ask a question, and get “Oh, well download and this and install it” as an answer. I quickly figured out that typically every “step” referred to would have about five presumed steps not expressly mentioned — such as, go to website x, look for packages appropriate to your distro and version, download it, and as root unpackage it this way, then do a makefile, etc. etc. etc This was frustrating even when I started figuring out what the presumed steps were — I still didn’t know how to perform the steps!

    I blogged on my reactions to Mel’s talk at http://www.malak.ca/blog/?p=363

    By Donald on Feb 3, 2011

  8. I have dug this up again to share with you another awesome open source (lack of) documentation analogy: http://jcreed.livejournal.com/1553512.html

    By Katie on Oct 9, 2011

  1. 5 Trackback(s)

  2. Feb 3, 2011: FUDCon 2011 — lightning talks « Don’s House of Fine Patisseries
  3. Feb 4, 2011: Tweets that mention [M]etabrain [E]ntry [L]og » Blog Archive » I’ve followed your instructions and I still can’t bake croissants -- Topsy.com
  4. Feb 9, 2011: The Grand Fallacy » XML editing with Emacs.
  5. Mar 6, 2011: [M]etabrain [E]ntry [L]og » Blog Archive » Tools for RSI self-care
  6. Mar 7, 2011: My participation at FUDCon Tempe 2011 « Don’s House of Fine Patisseries

What do you think?