This is a (rough) transcript of my lightning talk for FUDCon Tempe. For those looking for more resources, my talk was based on the Dreyfus Model of Skill Acquisition, 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, 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:
- But I have documentation!
- And I don't bite on IRC!
- 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.
Croissants
- 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>.
Omnomnomnom.
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.