"Richard A. O'Keefe" <ok at cs.otago.ac.nz> wrote:
> Daniel Vainsencher <danielv at netvision.net.il> wrote:
> 	Have you looked at 
> 	http://minnow.cc.gatech.edu/squeak/67? 
> I have.  Large chunks of it seem not to be there, like the Stream exercise.
Specifically, I was curious whether the exercises spread there and
elsewhere fit what people think is need to help someone new to Squeak
understand the "alpha to omega" aspect. If so, we can create a page with
a ordered collection of links to the most useful tutorials, and make
sure it is quite directly linked from the first documentation page. Have
you looked at any of these recently enough to help?

[R doc features]
Keeping in mind my interest in doing the easiest things that will
improve the situation, it seems to me like what we can take from that is
-

> (0) When you start R, it reminds you about the on-line help:
The help window in the image should point at the documentation page in
the Swiki.

> (1) At interactive level, if you want to be reminded about a function,
> (2) You can ask for help about a package:
> (3) You can ask for help about a function within a package,
> (4) You can search for a topic , e.g.,
I don't have particularly good idea. If the tools to find documentation
were more unified and trivial to use, more people would write
documentation, though.

> (5) Loading and installing a package over the internet is simple,
>     as is automatically updating one.  This also brings the documentation
>     across; there are never _two_ downloads.
This is the same as SM? or do they deal with depenedencies?

> (6) The process of building a package for distribution to others is
>     semi-automated, and there is a checking process which amongst other    
>     things checks that the documentation is there and the examples run.
We will be able to a lot in this direction with SM2.

> The manual pages for functions come to more than 2200 printed pages,
> and that's not counting all the packages available from CRAN.  The
> Smalltalk/Squeak source management stuff should make it practical to
> have this quantity of internal documentation for Squeak.
I think we should think about how the Swiki and "internal documentation"
can be made one. Nothing should be duplicated, the latest version should
be easy to access and contribute to, some easy form of caching for local
access should be easy. HOW we accomplish this is unclear.

> There's nothing here that Squeak *couldn't* do if there was the
> will to do it.
I'm biased towards thinking that the structure of the system can help
generate or completely kill the will. Tools are important levers.

> Perhaps the major difference between R and Squeak is that
> R is an attempt to build something that people can routinely and
> reliably used to do serious non-programming work, which is reasonably
> compatible with a commercial product (S-Plus). 
Seems to me like this also has the effect that the ways of doing things
are very well established, because they are similar to an established
commercial product. Some basic fixed well known routines can replace a
lot of documentation. We don't have that luxury (unless we limit
ourselves to people that know Smalltalk-80).

Daniel