Squeak Cookbook Style
Last updated at 1:27 pm UTC on 16 January 2006
An example of a cookbook with a good structure is the Perl Cookbook. Another example is the VisualWorks Cookbook mentioned in Thoughts on documentation as exemplary.
In the Perl Cookbook, recipes are structured like this:
- See Also
Each section has an introduction where some general concepts are explained. It closes with one or two complete useful example programs.
The VisualWorks Cookbook uses
- Problem or Action
- Basic Steps
- See Also
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.
We aren't currently following this guideline. I like the current version better, actually: the top page is like a table of contents, and then each recipe gets its own page. It seems impractical to put all of the recipes directly on the main page. What do others think? BTW, a Squeak cookbook is an excellent idea! -Lex Spoon
I agree. Keeping each recipe on a separate page makes sense. Also, I prefer to use the simpler Wiki way of adding an exclamation point (!) at the beginning of a line to get H3 heading size, and !! for H2, etc., rather than having a bunch of html formatting tags in there. But otherwise, the Problem/Solution/Discussion format sounds good to me. -Doug Way