Squeak
  links to this page:    
View this PageEdit this PageUploads to this PageHistory of this PageTop of the SwikiRecent ChangesSearch the SwikiHelp Guide
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:

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

Topics


The Cookbook should cover

Structure of the Cookbook


It makes sense to stick to a fixed set of HTML tags:

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