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@mindlink.net
------------------------------------------------------------------------------
Tansel Ersavas tansel@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:
- 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.
- 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@mindlink.net
-- Tansel
RASE Inc. 214W 29th Street Suite 901 10001 New York NY USA Voice: (212)584 8040 mailto:tansel@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)
squeak-dev@lists.squeakfoundation.org