documentation: sins of ommission

On a whim last night I tried to whip up Alton Brown's recipe for spinach salad.

Why, you ask. I'll tell you why. And thank you for asking.

It Looked Really Good When He Made It On His Show. Oh, and my wife loves spinach salad. Both Good Reasons.

But when I settled down with the recipe as documented at the link above, a few critical elements were missing.

Normally I'd just chalk this up to "life sucks" or "too darned bad". But how hard can it be to synchronize the recipe that is shown on air with the one that gets put on the website?

Here's one example that goes to the heart of the matter.

On the show, Alton set a large metal bowl on the gas burner and whisked the bacon fat, mustard, sugar, vinegar, salt and pepper together with the gas on. The goal here was not only to combine the dressing, but to get the bowl warm enough to wilt the spinach just slightly when it is added.

Is this reflected in the recipe? Ummm. . . no.

Would it be intuitively obvious to someone who had made thousands of spinach salads that this was the right way to do it? Ummm. . . yes.

But it was not documented.

What assumptions do you make about your users when it comes to your documentation, your UI layout, your use-case workflows? Are you doing the same thing to your users that Alton Brown did to me? Assume a certain level of practical understanding around mechanics on the part of the operator?

In the end, I figured it out. With enough motivation, we always figure it out.

But it left a bit of a bad taste in my mouth, an odd metaphor for making dinner.