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

Tue Mar 1 17:25:39 UTC 2011

Working on getting an image. Tentatively let's shoot to post on Friday.

As for inserting images within your text -- cc'ing Jason. He's a pro! 
Jason, can you help Mel?

thanks much.
MAB

On 02/25/2011 08:19 PM, Mel Chua wrote:
> 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.
>
> _______________________________________________
> Osdc-edu-authors mailing list
> Osdc-edu-authors at redhat.com
> https://www.redhat.com/mailman/listinfo/osdc-edu-authors