From Etel

Jump to: navigation, search

Here's a brief guide to cookbook correctness, wholesomeness, sweetness and light. For the real story, see Nat Torkington's original "Cookbooks in a Nutshell".

Anatomy of a Recipe

Cookbook recipes consist of five parts: a title, a problem description, a solution, a discussion, and a "see also" section for cross-references.

The title and the problem description are probably the toughest things to get right. I'll discuss them together.

  • The most important rule, with very, very few exceptions, is that RECIPES ARE ABOUT THINGS PEOPLE WANT TO DO TO ACHIEVE SOME RESULT. They may not know that they want to do it, but still: at some level, they want to do it. "Understanding Macros" is, therefore, a BAD recipe title. Nobody wants to understand macros; they want to *use* macros, to accomplish particular things. "Using Macros" is marginally OK, but weak; nobody says "Gosh, gee, I just learned about macros, where can I use them?". "Using macros to simplify your dialplan" is pretty good, but could be better. The grand prize winner is "Simplifying your dialplan with macros": it describes something every Asterisk users wants to do (dialplans are complex, and everyone wants to simplify them where possible).
  • Recipe titles almost always have a gerund in them. A gerund, for those who didn't remember their grammar in school, is an -ing word. Using, Fixing, Installing, Integrating: you get the idea. As I said in the previous rule, "Understanding" is almost always weak, even though it's a genuine gerund.
  • The title is a one-line statement of the problem. The description is a paragraph explaining the problem. It can say "For example" (though not right at the beginning). Logically, the function of the description is to convince the reader that he's got the right recipe. In other words: a reader looks at the title, such as "Configuring Music on Hold," and thinks "That sounds like something I need to know." He then looks at the description, which should confirm that he's reading an appropriate recipe: "You want to play annoying music to callers while they're waiting for their teleconference to start."

The solution is probably the easiest part of the recipe, unless you make it hard on yourself. It's the simplest possible straight-line solution to the problem: no variations, no complexity, no subtleties. All those go into the discussion. The solution also has very little commentary: it just tells you what to do. Again, explanation and commentary go into the discussion section.

The discussion is important: it explains the solution, shows variant cases ("If you really need to do X, then the solution won't work as shown; do Y instead"; "use the frob command instead of borz if you're using the VAX/VMS operating system"), and generally, says everything you wanted to say in the solution, but didn't. Discussions are not allowed to have subsections. If the discussion starts getting too long, think about whether you need to break the recipe into two.

Finally, the "See Also" section is a list of links to other sources of information: both other recipes, and external sources of information (both in print and online).

I've added a metadata section to the recipe template. As far as this wiki is concerned, it looks like the other parts of the recipe, but don't be fooled. The metadata is for our own use, helping us to organize, track, and credit contributors.

Other considerations

If you're just writing up things the reader "ought to know", it probably shouldn't be a recipe. A certain amount of background information (a couple of pages worth) can be stashed in the introductory section to each chapter. If it's going beyond that, it probably doesn't belong here.

If you're presenting reference information (API listings, command listings, etc.), it's not a recipe. However, cookbooks may have appendices; that's a more appropriate place for reference information.

Recipes should be relatively short, and often, the solution isn't complete; it just shows the relevant pieces. In a real (foody) cookbook, a recipe for Starfish a l'Orange probably won't tell you how to make the chocolate frosting; it would refer you to another recipe. That's also the case here. If things are getting too big, break them down. And remember: chapters can end with one or two "projects": fully worked out examples. We don't want too many of these, but one or two per chapter is fine.

Personal tools