Give the big picture and create a cook book (Documentation)
Last updated at 9:05 pm UTC on 14 April 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
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.