NatsCookbooks

From Etel

Cookbooks in a Nutshell

For examples of the Cookbook style, see Perl Cookbook and Java Cookbook. Do not see "Javascript Application Cookbook".

A Cookbook is divided into chapters, each chapter dealing with a particular subject (e.g., "Strings", "Threads", "E-mail"). Each chapter begins with an introduction, which lays out the concepts and basic techniques that will be built upon and used in the rest of the chapter.

The rest of each chapter is a set of numbered recipes and one or two short sample programs. There are typically 10 or so recipes per chapter (those in chapter 4 would be numbered 4.1, 4.2, 4.3, etc.). The introduction is not numbered, but the sample programs are numbered continuing on from the recipes (e.g., 3.11 Program: hopdelta). A recipe deals with a specific problem. It might address language issues as well as real world problems, but the content is always presented as a problem and its solution.

The structure of a recipe is as follows:

 NAME (always starts with gerund)
 PROBLEM (short description of the problem you're solving)
 SOLUTION (mostly code, but can have some text here too)
 DISCUSSION (longer description of how the solution works, pros and
   cons of alternate solutions, etc.)
 SEE ALSO (references)

The SOLUTION section can show multiple solutions. For instance, recipe 4.1 in the Perl Cookbook says

 Solution

 You can write out a comma-separated list of elements:
   [CODE]
 If you have a lot of single-word elements, use the qw() operator:
   [CODE]
 If you have a lot of multi-word elements, use a here document and
 extract lines:
   [CODE]

Notice that it's not just a list of code blocks separated by 'or'--there are very brief guidelines on when to use each different approach. That lets impatient people read the Solution and decide which approach is best for their situation.

It's okay to say "you can't do that". Recipe 3.9 in the Perl Cookbook has a SOLUTION that starts with

 This might not be possible.

It then goes on to show some non-portable 'works on some systems' hacks. So long as you flag them as such, it's okay to put those in.

We didn't use Word to write the Perl Cookbook, so didn't have the ability to use the 'replacable' style for the code snippets. We used all-caps variables to indicate replacables:

 $STRING = localtime($EPOCH_SECONDS);

We put in sample output, normally in the DISCUSSION section but occasionally in SOLUTION. It appeared in bold Courier.

In the DISCUSSION you'll put the detailed analysis of performance, which situation is better when, and the very weird variations and cool tricks you can play with the techniques of the SOLUTION. While some are longer (16.10 in Perl Cookbook) or shorter (3.10 in Perl Cookbook), the average recipe takes up a page or two, and usually most of that is the Discussion.

Not every Cookbook has to be an 800 page magnum opus that takes years to write. If you have a tightly-focused topic (e.g., DNS and BIND, rather than "System Administration") then the book should be a fairly straightforward matter in the hands of authors who know their stuff. For things like DNS, sample configurations may take a lot of space and bulk up the book. Because the configurations aren't prose (which is much harder to write and edit), the size of the book won't necessarily reflect the time it takes to write.

You probably won't want recipes for the absolutely trivial things like assigning values to variables. But if it's something that people do all the time, and which the average beginner doesn't know how to do, then by all means include it. For example, with DNS and BIND:

 Being primary for a zone
 Being secondary for a zone
 Adding a machine to a domain
 Creating an alias for a machine
 Defining the mail host for a zone

One way to avoid putting basic material in recipes is to put it into the Introduction to a chapter whose recipes will use it. For example, the introduction to the Perl Cookbook's arrays section talks about the subscript syntax and how to assigning values to particular parts of an array. The recipes in that chapter deal with searching, processing, and printing arrays, building on the basics from the Introduction.

In some cases the same basic technique needs to be referenced from multiple recipes. In this case put the technique into a recipe or introduction, and let the recipes talk about the application of that technique (optional extras, variations, performance implications, when to use it, etc.)