Documentation

Ralph Johnson johnson at cs.uiuc.edu
Wed Jun 9 05:09:30 UTC 1999


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.  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.

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.

-Ralph Johnson





More information about the Squeak-dev mailing list