=== Top of the Swiki === Attachments ===
Thoughts on Documentation
From the Squeak mailing list:
Date: Wed, 9 Jun 1999 00:09:30 -0500 (CDT)
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 nice for both patterns and cookbooks to point at examples
in the code. So, the swiki might eventually be enhanced to
point into the codebase. But in the 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 for a start.
See also: