The Trunk: Kernel-eem.1316.mcz

Ha! Thanks. I knew it couldn't have been a new idea :-)

Dave

On Sun, Mar 22, 2020 at 01:06:24PM -0400, gettimothy via Squeak-dev wrote:
>

Hi Subbu, Hi All,

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

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

> On 2020-03-22, at 2:36 AM, K K Subbu <[hidden email]> 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; [hidden email]; http://www.rowledge.org/tim
The world will end in 5 minutes.  Please log out.

On 23/03/20 3:29 AM, Eliot Miranda wrote:
> 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.

You're right! HelpBrowser is a great idea with lots of promise. Just as
CodeHolder extends StringHolder to accept and compile code into objects,
we need a HelpHolder be able to accept small text runs (paragraphs and
spans, figures, tags and links etc.) and weave them into a graph. We
could elevate the current comment node into such a holder.

The code holder, through which we accepted structured text, comes with
many facilities (e.g. explain, code completion, senders, etc). We need
similar facilities for accepting parts of help topics (e.g. class/ivars
name changes should be applied not only to code but also to the docs,
generate warnings about refs to deprecated classes/methods, identify
orphan nodes).

The current browser is designed for viewing/editing code. But to change
any large system, one has to build a mental model by studying existing
class hierarchy, instvars and methods and only then move into code-test
cycles. For people who work with Squeak daily, mental model is always
active. But weekend Squeakers like me will need to refresh our mental
models through reading. My typical workflow is - study topic, recall
hierarchy (with its instance vars) and then subclass or modify methods.
The code pane could start with the help topic swiki instead of the code
holder (subclass template).

In short, help topics should be a live and direct view into the object
graph of both machine-readable code and human readable text so every
code is browsed within this larger context. This will reduce most of the
tedium of keeping code and doc in sync.

Regards .. Subbu

On 23/03/20 4:16 AM, tim Rowledge wrote:
> 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.

Thanks for making it explicit. Yes, I include them under guide. The
Implementation part of BlueBook is an example.

My email was already too long, so I didn't elaborate further.
Essentially, a guide should help us understand the five aspects of a
system - Principles, Concepts, Facts, Processes and Procedures.
Researchers depend on the first two, programmers on middle three and
field support on the last two.

Principles deal with perpetual invariants in the system (e.g. everything
is an object, class-metaclass). This part does not change from release
to release. These invariants are what makes Squeak squeak ;-).

Facts also deals with invariants but these are subject to change in the
future releases through enhancement, deprecation or obsolescence. E.g.
Character is now an immediate object.

Concepts deals with new features introduced in a release (e.g. jit,
object representation, new bytecodes). Being new, the burden to create
new help nodes will fall on the authors. Others can step in to
interconnect these nodes into the help graph before release.

Processes deal with rules/rationale (why?), choice (tradeoffs) and time
(how? workflows?). E.g. Passwords should not be stored in clear text
(rule), why should ProtoObject be left alone (rationale). why can't we
get all instances of a Character (tradeoffs), how to submit a fix
(workflow). This is the most tedious part of writing help text. But if
other four are taken are of, then many people can step in to ease the load.

Procedures describe the precise steps (what to do) to be taken to
complete an operation (e.g. how to run benchmarks) or to work around
faults and exceptions. Squeak makes it easy to encode these into the
system itself. But if the method name changes, the doc should also be
changed to be in sync.

Regards .. Subbu

On 23/03/20 12:20 PM, Nicolas Cellier wrote:
> Hi all,
> since Tim raised the subject, let's return to caesar
> https://en.wikipedia.org/wiki/Literate_programming
> Otherwise, what Subbu said makes a lot of sense for me.

Thank you for your supportive words.

LP was a great idea for creating books or articles describing code in
languages like Pascal or C, but it doesn't fit our needs. Times have
changed. Squeak code graph is huge, live and 3D [1]. A static linear
rendering will be woefully inadequate.

[1] Craig Latta's Nexus demo https://youtu.be/xCwidGFkn4Q

I expect a modern guide to be like the guided tours in science expos or
film studios - live, direct, concrete and interactive. It should be
built with the same materials and operated by the same tools (staff) as
the rest of the system.

As Timothy and Tim have pointed out, we already have most of the low
level support (doclets, hypertext, help topics) in place. We need a high
level perspective and design to get them to work together to create a
seamless experience.

Regards .. Subbu

+1000.  One of the flaws of Literate Programming is that it presents a post-hoc rationalization of the code, not how it actually came to be.  Another is that it is designed to present a program rather than a library.  Documenting an evolving library, that includes executable examples and tests, is a different thing.

Something Alan Kay and I nearly started discussing on Quora is how to write unit tests as both specification and documentation of an API.  This could be literate programming done right.  It doesn’t fit every use case; only certain kinds of API (say sequence manipulation APIs such as includesSubstring:, copyReplace:from:to:with:startingAt:, and arithmetic).  But if the tests are written to be read as a guide one may be able to combine language/api specification with verification and documentation in the same single piece of executable code.

> [1] Craig Latta's Nexus demo https://youtu.be/xCwidGFkn4Q
>
> I expect a modern guide to be like the guided tours in science expos or film studios - live, direct, concrete and interactive. It should be built with the same materials and operated by the same tools (staff) as the rest of the system.

+1000. Somewhat related, see Tudor Girba’s examples extension of unit tests.

>
> As Timothy and Tim have pointed out, we already have most of the low level support (doclets, hypertext, help topics) in place. We need a high level perspective and design to get them to work together to create a seamless experience.

And you, Subbu, have they vision.  I especially liked your characterization of principles, etc, three or do messaged earlier in this thread.  Please push this.

>
> Regards .. Subbu
>