Hi Tansel,

I think we are attacking the documentation shortage from two
orthogonal directions, both necessary.  Your tool for "Dynamic
Document Capture" seems very useful for creating content, especially
for tutorials; one screen shot can save a thousand adjectives.
However, information once created needs to be organized and made
easily accessible, and this is where the documentation browser can be
helpful.  I think both tools will be needed; both should be developed.

Regards,
Stephen Ma <stephen_ma at mindlink.net>


------------------------------------------------------------------------------

Tansel Ersavas <tansel at rase.com> writes:
>
> 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-----


(begin news server fodder)
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
..
(end news server fodder)