[squeak-dev] self error: 'comment only'
K K Subbu
kksubbu.ml at gmail.com
Sun Mar 22 09:36:55 UTC 2020
On 21/03/20 11:51 PM, tim Rowledge wrote:
> Making good doc and good tools to make that easily available and easy
> to keep up to date is hard work. I think we have a lot of decent
> starting points though. We can, for example fetch swiki pages fairly
> easily, which would be a great thing to improve for major doc items.
Separating document from code has never worked out well in the past.
Code is for machine to execute and no amount of comments embedded in
code will replace a proper narrative guide intended for programmers.
When reading such comments, I tend to miss the forest for the trees.
Most documents that have endured in the past (The C Programming book by
K&R, anyone?) fall primarily into two types: guides and references. The
guides are compact narrations intended for on-boarding programmers. The
references are comprehensive dictionaries intended for lookup by
experienced programmers. One could refine these into more sub-types
(like tutorials, cookbooks etc), but these two are essential and
sufficient (for small self-supported groups like us).
Examples of the first kind are - Introduction to Morphic, Back to the
Future, Etoys Quick Guides. These are difficult, but not impossible, to
get off the ground and need support from the code (e.g. for active
essays). Whenever a new concept or design is introduced in a release, a
chapter/section/glossary should be added to it (even if empty). In
Squeak, it is easy to write small narrations as active essays and update
them every Squeak release. We do this already in bits and pieces but we
need to put all the wood behind a single arrow.
The class comments and terse guide belong to the second category. They
can serve to refresh memory but are not substitutes for a proper
narrative. Comments like whatIsAPrimitive should be merged into a
narrative flow rather than stick out in isolation.
While I use Squeak swiki, I feel it is inferior to an in-image guide.
Swikis don't let me switch into browsers or inspectors. We could write
narrative texts as Help topics and books and use a in-image swiki server
to export to HTML on the fly (or produce PDFs for offline reading).
Topics can be patched with changesets just like code. An in-image guide
and swiki server may add an extra 2-3MB but it would take less effort
overall in keeping them in sync with code. Experienced developers can
always strip them out from production images if size becomes an issue.
I am not in favor of placing guides outside Squeak image and using
in-image PDF or WWW browser to read them. Browser specifications have
become too baroque and complex for any sane implementation. An in-image
browser would result in a huge code bloat and divert efforts away from
the core product.
Regards .. Subbu
More information about the Squeak-dev