[Osdc-edu-authors] Croissants article draft up, ready for review and images

[Mel Chua]

http://opensource.com/education/11/2/i-cant-bake-croissants-fable-project-documentation 
- article text below. Thanks to Bascha for the editing!

I'd like to include the (CC-BY-SA) images from 
http://blog.melchua.com/2011/02/01/ive-followed-your-instructions-and-i-still-cant-bake-croissants/ 
in a slightly different order/spacing to make it flow better with the 
revised text, but (once again) can't for the life of me find the picture 
upload form. And need an artist to create some sort of title image 
thing. Help?

When do we want to push this?

-----

This article was originally a 5-minute lightning talk delivered at 
FUDCon Tempe.

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?

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 interact with folks on IRC, 
and within moments, I can answer: "All right, I see what your problem is."

Now, instead of explaining this for software, I'm a little hungry, so 
I'm going to talk about croissants.

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, so I look online for some bread 
recipes. I might come across a recipe that looks like this:

Croissants

     * flour
     * butter
     * stuff

Mix then bake it!

Ask me if you have questions!

And I promptly go “bwuuuuh?” and ignore everything—I don't know where to 
start. I'm not even sure what you're talking about and what I want are 
the same thing. I mean, what the heck is a croissant?

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

Croissants: tasty flaky buttery bread

     * flour
     * butter
     * stuff

Mix then bake it!

Ask me if you have questions!

Right! Bread! The thing I’m trying to learn to bake! I might actually 
want to make this stuff now. I’m still not sure exactly how I do that, 
though.

What’s that list of stuff? How do I bake it? Nobody told me, so I went 
out and got flour, butter, and... some stuff  - lemon drops and 
marshmallows are stuff, right? So I put it in a bowl to mix it and now I...

Oh, shoot. You’re telling me I needed to get an oven beforehand? And 
preheat it? What does that even mean? Have I done something terribly wrong?

Should I give up and go away?

In contrast, look at this WikiHow guide to croissant-making. There's a 
clear ingredients list: 4 cups flour, 1 Tablespoon active dry yeast (2 
packets), and so on. There are steps. They're illustrated. They tell me 
what the dough should look like ("smooth elastic consistency") and how 
long each step will take ("until it doubles in size... should take 1.5 
to 2 hours.") Heck, step 20 even tells me to turn the oven on so it's 
preheated and ready to go in step 22, and there's a list of things that 
go well with croissants (butter, jam, ham, cheese) at the end. And 
there's a picture of the end result that makes my mouth water.

We know these clear step-by-step instructions are important in a 
cookbook because we’re mostly novices in baking-land. We can’t just 
improvise through because we don’t know how these ingredients are going 
to interact with each other; we aren't familiar with pastry-making, so 
even common tools and techniques will be unfamiliar. We’ve never made 
(and maybe never even eaten) croissants before so we can’t visualize the 
process or the end result without help.

We don’t have context.

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

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

They’re understandable to us as experienced software hackers – most of 
the time when we write documentation like that, we’re merely providing 
an example of something we've done ourselves dozens of times in testing. 
We're experts. We’ve done it all before, we know what to expect, and 
rough notes are sufficient for us to reproduce past results.

But our audience is not. Context is important. Experience is important. 
And you can never assume that your audience—those who follow behind 
you—will have had either, and especially not in the exact same ways that 
you have had.

So if you're wondering why people don't follow your instructions to help 
you with your project, hit your local library and check out a cookbook. 
Bake something you've never baked before. (If you're a good baker, try 
to prepare a vegan dessert or a gluten-free bread - do something 
unfamiliar.) Notice what it feels like to be a novice. Notice which 
instructions make you feel nervous and which make you feel confident. 
Then, while eating the fruits of your labors, open your documentation 
again and take a look at it with your "beginner's mind."

If you'd like to learn more about the differences betwen novice and 
expert thought in any given domain, check out the Dreyfus Model of Skill 
Acquisition, which is secretly what this entire bit on croissants has 
been about.

That's all the time we have for today. Thank you.