I agree very substantially with you on this, but not completely.

> On 2020-03-22, at 2:36 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.

Dan Lanovaz (an old colleague of mine & Eliot's) used to say "Don't document the program, program the document" which I like as a pithy way of illustrating how badly the software world does things in general. He also hacked up a neat trick to make a Word doc file go through a compiler such that the code would be seen by the compiler and all the rest was treated as comment. Thus a nicely written design doc could (in theory) actually contain all the code. This is not massively different to some of the things Alan Kay has used for demos over the years.

It's certainly true that code (class/method) comments are not usually a good place for information about the wider system/package, no matter how conscientious the programmer is. 

> 
> Most documents that have endured in the past (The C Programming book by K&R, anyone?) fall primarily into two types: guides and references. 

Maybe you would include them in your list of 'guides' but I'd say there is a third type, the system description; not a bare operation by operation reference but a soldi description of the intent, limitations, usage and ethos of the system.

> 
> 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.

Definitely with your there.

> 
> 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.

Yup.

> 
> 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.

OK, now there we part ways a little. I suspect you're sticking the swiki into a box labelled 'www & browser' which I am going to claim isn't really the case. Yes, the swiki lives on the web and can be accessed by a full blown (and boy, do most of them blow) browser. BUT since the swiki syntax is much simpler, and indeed under our control, we *could* decide to extend the swiki server to return the bare swiki-text and then have a swikibrowser in the HelpBrowser. 

This would mean we could render it our way instead of using www circumlocutions. It would have some problems with pointers to outside URLs, obviously. But we really don't need to parse html if we get the swiki-markup text. We could, I think, make a HelpBrowser that reads the input and handles our images and texts and links and whatever. It could read that input from anywhere we like including in-image or online or files included with the release just as we  include i18n translation files.


> 
> 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.

Definitely no need for a full html parsing monstrosity. But a swiki-capable browser is much less of a 'thing' - indeed we already have a lot of it in the image I suspect. Consider the Book, TabbedPalette, StackMorph & related morphs.

And of course, tools are great but it's meaningful, up to date, useful, content that is the essential...


tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
The world will end in 5 minutes.  Please log out.