The day I tried to make cookies and learned something about writing documentation

Have you ever wondered what it might feel like to read product documentation without the benefit of being an expert in the product? It’s a frustrating exercise, but it’s usually something I can work around once I figure out the gap between what I know and what the reader knows.

It’s never been brought home so completely as it was the other day. I had a hankering for some home-baked cookies and, perhaps stupidly, I figured I’d cook them myself. After all, how hard can it be to follow a bunch of simple instructions to bake some cookies, right?

So I enthusiastically embarked on the cookie-baking journey. After a little trawling on the web, I gave a shout out to my friends, asking them to send me their favorite recipe.

This one came back from a trusted expert who runs cooking workshops and her own cake business. Suffice it to say, she knows what she’s doing and because of that I chose to try hers.

🔗White Chocolate and Macadamia Cookies

🔗And the adventure begins

After measuring out the ingredients carefully, things started to fall apart. The first step should have read, “Soften butter by microwaving on high for 30 seconds,” then, “Using a whisk, beat butter until light and fluffy.” Neanderthal that I am, I threw the butter straight from the fridge into the bowl with the other stuff and started pounding it with my fists. It became neither light nor fluffy, although the batter got to a point where I felt that it was probably time to add the eggs.

I followed the addition of eggs with more pummeling, and then I hit my first conundrum. In Australia, “g” means grams, but when I got to this line “2 to baking soda” I had no idea what a “to” was. I tried to phone my friend but she was unreachable at the time, so I just went ahead and assumed that it was a typo and that she meant “teaspoon,” but upon reflection, it could have meant “tablespoon.”

How much is a “splash”? A “splash,” it says! And how do I “splash” vanilla seeds? I solved the latter by digging around for some vanilla essence, but I agonized over the “splash.” In the end, I figured a teaspoon would probably be enough, but to this day I still don’t know.

The next instruction was perplexing, too. What is mixing gently, and how does the lack of rigorous force change the way the cookies taste? I searched the internet for techniques on “mixing gently,” but all I achieved was getting smears of cookie dough on my iPad. Rapidly losing patience and getting hungry, I just mashed what was in the bowl so that it looked evenly mixed before throwing in the macadamias and milk chocolate pieces.

I was convinced I was ready to bake. All I needed to do was to “form the mixture into balls and spread out on a lined baking tray”…but how big is a ball? What do I line my baking tray with?

Twenty minutes later, my first batch came out, and they were not the cookies I was looking for. They seemed really dry, so I added more butter and tried again. Another twenty minutes went by, and they still looked wrong. So I added a bunch of honey. I know it wasn’t part of the recipe, but I saw that another recipe called for it, and I was desperate. The last batch came out looking somewhat like the cookies I had imagined creating, but after the first bite, well, let’s just say there was no second bite.

🔗Aftermath

This adventure got me thinking about the documentation I produced for software projects in the past. I never really gave any thought to who the person reading that documentation would be - their background, skills, or experience. I just assumed they’d be familiar with all the things that were obvious to me.

It’s clear now that my first mistake was pulling all the ingredients out of the pantry. I should have read a book on cooking — maybe even read how to operate the oven instead of twiddling the dials until it looked right. Let’s face it: we’ve all had days in our careers when that method of trial and error produced code that’s still in production today.

Beginners shouldn’t assume instructions are written with the reader’s level of competence in mind. Likewise, authors must be mindful that the audience for their expertise might be completely oblivious to what they think is glaringly obvious.

When my friend handed me the recipe, she had assumed that I wanted to bake because she loves the process. In fact, all I wanted was cookies. The truth is many people don’t care about your motivations or what you know. They only care that your writing makes their lives better in some way. They will happily find something else to read, or worse, write nasty comments if you don’t live up to their expectations.

🔗What to focus on next

It’s easy to be dismissive of documentation, especially when you’re in a big organization and the documentation hot potato is being tossed around. Next time, don’t pass it on. Make it the most important thing you do that day.

Aside from spelling and grammar, you need to think carefully about your audience and optimize the information for them. Before you publish, read it out loud - even to your cat (who is probably sitting on your keyboard anyway). Does the information still make sense?

This might also raise some questions about the information you are providing. Think about the quality of your communication. Is your writing clear and precise? Are your assumptions about your audience reasonable?

At Particular Software, we endeavor to make our documentation as relevant and useful as possible. We think our docs are pretty good, and our team is always looking to improve them. If you notice something that is confusing or needs attention, you can simply click the “Improve this doc” button and submit those changes or any comments you have through our GitHub back-end.

🔗Additional reading

• Winner’s curse - Wikipedia
• Curse of knowledge - Wikipedia
• The Curse of Expertise - Psychology Today
• Four Secrets To Lift The “Curse Of Expertise” - Annie Murphy Paul
• Making Badass Developers - Kathy Sierra (Serious Pony) - YouTube

About the author: Peter Giles is a developer at Particular Software, is passionate about riding his Harley, and enjoys a good cookie.