[DOCS] Re: Squeak Documentation Project
dway at riskmetrics.com
Fri Feb 7 00:09:38 UTC 2003
I generally agree with Göran's points here. The only things I would add are:
* Yes, continue the discussion on this list for awhile before creating a
separate list, but you could also add a prefix such as [DOCS] to the subject
line for these discussions. If these discussions actually keep going, and we
have, say, over 100 messages on the subject, then it might be time to start up
a separate list.
* Definitely use the GaTech Squeak Swiki as a starting point, rather than a
separate swiki. There is quite a bit of documentation on the Swiki, while
sometimes disorganized, could be directly linked to from your pages. I see
that someone has already started by creating an "SDP" page on the Swiki, which
could be one starting point for discussion. (One thing I would change on that
page is to change the links at the bottom to things like *Basic Squeak
Development Tools* instead of *http://minnow.cc.gatech.edu/squeak/4*.)
And of course, documentation integrated with the image would be nice. :-)
- Doug Way
goran.hultgren at bluefish.se wrote:
> 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
> 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