Tansel Ersavas tansel@rase.com writes:
Reinier van Loon wrote:
I am more or less busy documenting Squeak using [Paradigm Plus]. [Found a possible inconsistency in Controller re: Sensor] [Volunteer to maintain a list of similar oddities]
[Describes a nice tool for generating graphical class diagrams in HTML]
http://www.rase.com/cybercards/db/ccm.htm (click on the subsystem and class icons in images)
[Above URL may disappear because it's supposed to be sort of secret, so see it soon!]
The disadvantage of doing all these is in Paradigm Plus is it is a pain, especially to redo parts of it every time the system changes.
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.
... [snip] ... although normally this system is for sale for VSE (and soon VA), I'll make it freely available for Squeak community for learning and developing Squeak (I'll still ask people who use it for commercial purposes to buy it though).
When it is ready to be tested, I will let everyone in this group know so that people can download and play with it true to the culture of Squeak.
I'm looking forward to it!
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.
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.
What do you people think?
------------------------------------ Stephen Ma stephen_ma@mindlink.net
Folks --
I feel very positive and supportive of both suggestions. Our motto is "The system is the curriculum", but we have yet to make good on this, and appreciate very much everyone's interests and contributions in this important area.
Best to all,
Alan
-----
At 8:04 AM -0800 3/28/98, Stephen Ma wrote:
Tansel Ersavas tansel@rase.com writes:
Reinier van Loon wrote:
I am more or less busy documenting Squeak using [Paradigm Plus]. [Found a possible inconsistency in Controller re: Sensor] [Volunteer to maintain a list of similar oddities]
[Describes a nice tool for generating graphical class diagrams in HTML]
http://www.rase.com/cybercards/db/ccm.htm (click on the subsystem and class icons in images)
[Above URL may disappear because it's supposed to be sort of secret, so see it soon!]
The disadvantage of doing all these is in Paradigm Plus is it is a pain, especially to redo parts of it every time the system changes.
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.
... [snip] ... although normally this system is for sale for VSE (and soon VA), I'll make it freely available for Squeak community for learning and developing Squeak (I'll still ask people who use it for commercial purposes to buy it though).
When it is ready to be tested, I will let everyone in this group know so that people can download and play with it true to the culture of Squeak.
I'm looking forward to it!
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.
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.
What do you people think?
Stephen Ma stephen_ma@mindlink.net
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@mindlink.net
squeak-dev@lists.squeakfoundation.org
-
Alan C. Kay -
Stephen Ma -
Tansel Ersavas