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