Squeak Documentation Project

Hernan Tylim hptylim at dc.uba.ar
Thu Feb 6 16:52:24 UTC 2003


Hi,
	If you don't mind my opinion I would like to say that better than having a
super-multimedia-hipertext-help-manual on squeak would be to have class
comments on every class.

	Just my 2 cents

Regards,
Hernán

> -----Mensaje original-----
> De: squeak-dev-bounces at lists.squeakfoundation.org
> [mailto:squeak-dev-bounces at lists.squeakfoundation.org]En nombre de
> goran.hultgren at bluefish.se
> Enviado el: Jueves, 06 de Febrero de 2003 08:05
> Para: shane at shaneroberts.com; The general-purpose Squeak developers list
> Asunto: Re: Squeak Documentation Project
>
>
> shane at shaneroberts.com wrote:
> > I think Chris Burkert has made a great suggestion for getting
> > newbies more quickly integrated into the community, helping them
> > learn Squeak, and contributing by writing.
>
> I agree with the general idea. Let me just (as one of the Guides) give
> some pointers and some advice/ideas/remarks.
>
> > I volunteer to:
> > 1)  coordinate the setup of the Swiki page
> > 2) coordinate setup of the squeak-doc mailing list
>
> Both the above can probably easily get done by talking with Cees de
> Groot. He is the man hosting both the mailinglist and the SqF Swikis.
> BUT... before doing this let me just say a few things:
>
> 1. A new mailinglist is probably not the best thing. I have seen
> multiple parallell lists come and go over the years (modules etc) and
> many of us prefer the simplicity of just having one or two lists to
> follow. Currently I follow the SqF list (where the Guides "hang out")
> and the Squeak-dev list. My advice is to wait with the mailinglist and
> stay here on Squeak-dev until the traffic really gets annoying.
> Otherwise you are risking death by suffocation (=no readers) even before
> you get rolling. :-)
>
> 2. A Swiki intended for just documentation of Squeak has been tried and
> failed before. Of course this doesn't mean that it will fail now of
> course - I have known to be wrong on occasion :-). There are also today
> quite a lot of documentation on the Squeak Swiki. I am not promoting to
> simply continue to use that Swiki (well, for starters - but see below
> for the Grand Pla), but on the other hand I think that a new Swiki will
> compete with the Squeak-swiki (just as the old one did) and probably not
> win. Remember that the Squeak Swiki is searchable and that people don't
> like searching in multiple places.
>
> So, my advice - take it or don't - are:
>
> 1. Stay here on Squeak-dev to begin with.
> 2. Wait with creating a new Swiki and instead create a Swiki page on the
> Squeak-swiki describing the plan and the team you have managed to
> "gather" and who is meant to do what. But before you even do *that* -
> search the Swiki because IIIRC there have been other similar
> documentation attempts started before you...
> 3. Begin by doing an inventory. What do we have today?
> 4. Take a deep look at how the documentation should be created. I am
> personally a bit sceptical of the use of a Swiki - see argumentation
> below.
>
> I don't think that "system documentation" should be outside of Squeak in
> HTML or as a printed book. As supplementary formats - sure, but not as
> the primary source IMHO.
>
> As with all "separate" documentation it will simply wither, rot and die.
> ;-) We have seen it before. The same problem actually exists with *code*
> outside of the current base image (and this is one of the challenges of
> the new world of packages) - code that people don't see inside their
> typical image is very easily forgotten and thus will eventually rot
> (turn incompatible).
>
> I would rather like to see documentation created inside Squeak - I mean,
> hey - Squeak is a superb multimedia environment where stuff can be
> demonstrated and interacted with. And I would bet on the fact that Alan
> agrees with me on this. :-)
>
> Currently we have class comments, example code and sample Projects (many
> on the SuperSwiki). Perhaps we should create some form of integrated
> documentation inside Squeak right there together with the code? Yes - it
> is the good old idea of Knuth. Documentation separated from the code
> will always get stale. The XP people have also re-realized this and
> their solution is to simply skip documentation (more or less)! The Knuth
> solution was to interweave the code and the documentation so that
> neither is separate, thus forcing them to be "in synch".
>
> I would promote something in the lines of Knuth - not by interweaving
> with the code perhaps, even though some form of "links" between the code
> and the docs is needed in order to keep them "glued together".
>
> Rather a nice interactive "book" in Squeak with a TOC, index,
> introduction chapters, search capabilities and integrated runnable demos
> would be fantastic and quite plausible.
>
> If I change the code in a class that is used/documented inside the
> interactive documentation then I should be alerted or even (more or
> less) forced to review the docs too. It is simply *fundamental* for the
> success of such an effort that the code and the interactive manual are
> kept synchronized.
>
> And finally - HTML and/or printed docs could probably eventually be
> produced from this interactive book. But the need wouldn't be that high
> of course.
>
> > 3) Administer SwikiDoc
> > 4) And write documentation
> >
> > How do we get a consus for go ahead on this?
>
> Well, we can start by fleshing out the "plan" a bit more - I like things
> to be very concrete. And then if all Guides are "for it" then you could
> IMHO take that as "go".
>
> regards, Göran
>
>
>



More information about the Squeak-dev mailing list