Documentation within the Image
Last updated at 1:49 am UTC on 26 July 2013
Writing Class and Method comments is probably the easiest contribution to make, and it is enormously helpful.
The Squeak Documentation Team has decided to begin their commenting efforts with Seaside:
- More outsiders are interested in Squeak due to Seaside more than any other project. Hard documentation effort here will help unclog the largest barrier facing wider Squeak adoption
- The Seaside community is quite active, and so there will be a lot of drive for this effort to succeed, as well as a lot of help to get there
- Seaside is highly visible within and without the Squeak community, so the doc team stands to gain a lot of recognition and reputation by doing a good job of Seaside documentation
- Clean Up the Swiki - review the swiki and update or clean up its documentation. This includes:
- Develop a set of paths or "guided tours" within Squeak. Use the hyperlink feature in the Squeak class documentation. Point of depart is probably the Object class. A tour could go to the collection classes; a second to the basic GUI classes; a third to the Morphic classes; a fourth to the Swiki classes ....
When studying an unfamiliar piece of code, you will need to take a few notes to remind yourself what that class or method does, and a model of how it works. There is no better place to put those notes than into the official image. Once you have a few written, it is very easy to submit them for inclusion into the official image. In fact, Göran Krampe had some suggestions on Making a change set with only comments.
Other forms of in-image documentation:
Some classes may be better documented here than they are in the image. We should probably delete the class documentation from this Swiki unless it is auto-generated from the image. Here is a list of some of the classes that are documented here:
Classes for which documentation has been explicitly requested:
[13 Aug 1999, Dwight Hughes] For myself, the ultimate goal I would like to see Squeak achieve is to equal and then exceed the integration and capabilities of the Symbolics Genera DocumentExaminer documentation system (http://kogs-www.informatik.uni-hamburg.de/~moeller/symbolics-info/docex/docex.html). They were actually not too far from a true literate programming system. Part of what made this work so well is the fact that most of it was based on a document database structure, not just flat texts. Mind you - there are a lot of steps between here and there.
See also Literate Squeaking