Stephen Ma wrote:
[snip...]
 
> I agree.  In my experience, the only way to maintain consistent
> documentation in a rapidly evolving system like Squeak is to attach
> that documentation as tightly as possible to the code. 
> 
> I'm looking forward to it!

Thank you
 
> However, Tansel, I have a feeling that even your utility may not be
> enough.  There's also a desperate need for overviews and tutorials;
> these tend not to fit well into Smalltalk's traditional hierarchy of
> classes, categories, and methods.
> 
> Hence I propose a "documentation browser", similar in appearance and
> behavior to the system's other multi-paned browsers, which allows
> people to navigate and modify an independent hierarchy of "books",
> "chapters", "sections", and so forth.  There would of course be
> hyperlinks, not only to points within the documentation hierarchy, but
> also to class and method comments.

I totally agree with what you are talking about and one part of my tool
deals with it. I called it "Dynamic Document Capture" which has two
aspects: 
1. Captures information from a running window and automatically creates
a document for that window cutting and saving bitmap image of the window
itself, and each widget to an image (including whatever information that
widget contains at that moment), and creating a title for each image, so
that the writer of the documentation can come up with some meaningful
text explaining that window and/or widget. The entire information is
kept in the image with hyperlinks, and saved, filed out and in with the
source.

2. Allows a mechanism to capture sequences of events suh as pop-up menu
selections or modal dialogs with images and allows the user to document
these events

Using these techniques one can evolve an on-line help system while the
program is running as well as capturing essential information that can
be a basis of "dead" documentation such as HTML or RTF

> The documentation browser would sit on the desktop, and would probably
> be the first thing any new Squeaker sees.  If books like "Squeak
> Tutorial" and "Morphic Guide" were this easily accessible, I think
> Squeak would become much more approachable.
> 
> Here is a wild idea: why not make the tutorials interactive?  After
> all, we have the full power of Smalltalk behind every page.

This is another thing that can be done locally as well as with something
like a wiki-wiki server, assuming most tutorials will be available on
the web, a wiki can  calculate expressions and convert results to a HTML
page even when one doesn't have a local copy of Smalltalk. However there
are security and integrity problems. Using certain templates to allow
only certain expressions can help a great deal but very inflexible.

What about linking a local copy of Squeak to a server to make the client
run some chunks of code as if it were typed from the keyboard to run on
the client machine? That way a tutorial could discuss an example, even
execute it step by step and display intermediate results on an HTML
page, and at the click of a button this example or a variation of it
would be downloaded to a browser for the user to play with and test in
their environment.

Tutorials on the image have the danger of being quickly outdated, and
inflating the image far beyond what it is now. Also it helps to
centralize these tutorials to a few locations in the web and hopefully
all linking them together so that the thing evolves to a  huge body of
information that can be accessed from anywhere but doesn't bulk up the
image.

> What do you people think?

Great
 
> ------------------------------------
> Stephen Ma <stephen_ma at mindlink.net>

-- 
Tansel
-----------------------------------------------------------------------
RASE Inc. 214W 29th Street Suite 901              10001 New York NY USA
Voice: (212)584 8040                             mailto:tansel at rase.com
Fax:   (212)584 8042                               http://www.rase.com/
-----"violence is the last refuge of the incompetent" Isaac Asimov-----