Recipe:

Understanding the Cookbook format


Problem

You want to contribute, but aren’t familiar with the Cookbook format or don’t know how your contribution should be formatted.

Solution

Cookbook-style guides contain recipes that guide a beginning programmer to a deeper knowledge of the subject by answering specific, “how-to” style questions. Cookbook recipes address more topics than API documentation for a class, but are smaller in scope than a topic-based guide.

All recipes follow the same format:

Title
Broadly explains the topic of the recipe
Problem
Outlines the recipe's goals
Solution
Summarizes the correct approach to addressing the problem
Discussion
Explores the solution in detail

A Cookbook does not need to be read in any particular order, and each recipe should contain all the information necessary for a beginner to address the problem statement. Referring to other recipes that are considered prerequisite knowledge is encouraged.

Discussion

Take a look at an O’Reilly Cookbook or the Coffeescript Cookbook. Both of these are great examples of the Cookbook format.