=== Top of the Swiki === Attachments ===
Squeak Cookbook Style
An example of a cookbook with a good structure is the
Perl Cookbook. Another example is the the VisualWorks Cookbook mentioned in Thoughts on Documentation as exemplary.
In the Perl Cookbook, recipes are structured like this:
- Problem
- Solution
- Discussion
- See Also
Each section has an introduction where some general concepts are explained. It closes with one or two complete useful example programs.
How is it in the VisualWorks Cookbook?
The VisualWorks Cookbook uses
- Problem or Action
- Strategy
- Basic Steps
- Variants
- See Also
Topics
The Cookbook should cover
- some Smalltalk-related stuff like "Doing something to each element of a list / collection"
- Morphic recipes
- useful addons
- ...
Structure of the Cookbook
It makes sense to stick to a fixed set of HTML tags:
- Use H1 for headings like "Recipes" and "About the Squeak Cookbook"
- Within the Recipes section, use H2 to arrange recipes into groups
- Use H3 for the heading of a recipe.
- Use H4 for the elements of a recipe, such as Problem, Solution, See also.
This structure makes it possible to process the cookbook automatically if that should become necessary, e.g. for creating a table of contents, or for moving large recipes to separate pages.
see also Practical Wizardry