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