links to this page:    
View this PageEdit this PageUploads to this PageHistory of this PageTop of the SwikiRecent ChangesSearch the SwikiHelp Guide
Give the big picture and create a cook book (Documentation)
Last updated at 9:59 pm UTC on 17 August 2018
A note by Ralph Johnson, June 1999, on documentation

From the Squeak mailing list:

Date: Wed, 9 Jun 1999
From: Ralph Johnson
Subject: Re: Documentation

API-level documentation

My experience is that API-level documentation is not as important for Smalltalk as it is for other languages, because it is so easy to read the source.

"Big picture" and cookbook

The kinds of things that need to be documented in Smalltalk are the kinds of things that you can't get easily by reading the source, such as the big picture and how to do a particular task. Part of the motivation of patterns is to be a way to describe the big picture a piece at the time, and also a way to describe how to do a particular task. However, tasks might be better described by the class "cookbook". The VisualWorks Cookbook is a very good example of how to do this for Smalltalk.

Use this wiki!

A wiki is a very good way to capture documentation like this. It is meantime, people can just add things as they realize they are important. A good way to start is just to answer questions as they are asked, and then to organize the answers. There seem to be a lot of questions about Morphic, so that might be a good place to start.

See the Squeak Cookbook.