There is some very good guidance in this note. Thanks Subbu.

Dave

On Sun, Mar 22, 2020 at 03:06:55PM +0530, K K Subbu wrote:
> 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
>