Hi Subbu, Hi All,

> On Mar 22, 2020, at 2:37 AM, K K Subbu <kksubbu.ml at gmail.com> 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.

+1000

And in-image the problem is not so much the form of the documentation as it is bringing it to the attention of the programmer.  If we were in the habit of reading the image, as we were in the ‘80’z when it was a small fraction of its current size, then we would all be familiar with and I surprised by Object’s class side documentation, and be in the habit of checking the class comment if every class we browse.  But we’re not and a key party of this is just a scaling problem.

What I think Subbu’s analysis and this scaling problem implies is that the Help Browser is a great central location to go to to find documentation, but the Help Browser will be better if it is able to display class comments and documentation methods as well as its own help pages.  My vote is to make the Help Browser multi-modal and about indexing tool for accessing help and documentation in as many turns as possible, including pointers to web pages and videos.

> 
> Regards .. Subbu
>