Join the 85,000 open source advocates who receive our giveaway alerts and article roundups.
I can't bake croissants: a fable on project documentation | Opensource.com
I can't bake croissants: a fable on project documentation
Get the newsletter
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:
- But I have documentation!
- And I don't bite on IRC!
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:
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
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?
based on cornetti1 CC-BY-SA-3.0 by exeair
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.
This article was originally a 5-minute lightning talk delivered at FUDCon Tempe.