Documentation, more, more

Gary Fisher gafisher at sprynet.com
Mon Sep 1 11:21:58 UTC 2003


Hi, Leftie!

(I happen to be profoundly sinistral myself, by the way, and quite happy
about it. :-)

One reason Squeak documentation can appear to be hard to find is that there
are multiple versions or aspects (or perhaps viewpoints) of Squeak.  Much of
the Squeak-Dev view exists primarily to hone the cutting edge of Squeak; a
good deal of what's here is experimental, even speculative, and may never
get beyond that stage.  A substantial portion of the Squeak-Dev view is more
practical or explanatory, though it still leans more toward advancing the
user than simply to plonking him or her down in a quiet spot.  This list
tends to have a headlong feel.

For a viewpoint more suited to teaching (with) Squeak, you might find
Squeakland (www.Squeakland.org) and the list available there more to your
liking.  The Squeakland site and list are devoted much more to practica,
based on the most current "stable" version of Squeak rather than the
development version du jour.

If you're looking for the fastest way to get working with Squeak, however,
you might find one or more of the published references best suited to your
needs.  Mark Guzdial's books, in particular, can take you from installation
to coding to eventual understanding in what may well be the shortest
possible time, though by necessity any printed text will be based on the
version of Squeak available at the time of printing (included on the CD
bound with each book), which will of course not be the most current version.
Nevertheless, moving independently from a good working knowledge of an
earlier Squeak to today's version will probably be easier than coming in
directly from complete Newbiedom.  I purchased my copies of Mark's books at
a local book store (a good opportunity to encourage them to stock more
Squeak and Smalltalk books) but a quick Amazon search will bring up both new
and used copies at good prices.

I hope that helps.

Gary Fisher

----- Original Message ----- 
From: "leftie2100" <leftie2100 at yahoo.com>
To: "The general-purpose Squeak developers list"
<squeak-dev at lists.squeakfoundation.org>
Sent: Sunday, August 31, 2003 6:19 PM
Subject: Re: Documentation, more, more


Considering the supposed emphasis on using Squeak as a teaching tool,
I guess I find these reasons to be a really poor excuse. What good is
a great tool to the public as a whole if the only people who can use
it are the developers?

The lead developers need to make development of good documentation
just as central to releases as the code itself. Until they demand that
documentation be completed and updated before software is released, it
won't be. The lead developers need to take charge of the documentation
process instead of allowing themselves to let others take this "chore"
off their hands. The attitude I'm seeing here that the documentation
is a necessary evil that must be "grinded out' sounds like it very
well could be a significant part of the problem. Writing can be fun to
do if you go about it in a light-hearted fashion and that type of
writing also engages the reader.

Personally, I know a bit about writing, but I know nothing about
programming.  I'm a programming newbie that would really like to learn
Squeak, but I'm pretty much kept from doing that because of your
current documentation situation. I read this list because I keep
hoping I'll read some new focused learning resources have been
created. So when I read that many feel "coding is fun, documentation
is not" on the threads, it doesn't do much for my confidence that I'll
ever get the chance to use Squeak.

If you guys really want to be the Squeak evangalists you seem to all
claim you want to be, you're going to have to have a complete attitude
change about things like complete centralized documentation and the
creation of Squeak programming texts for those new to programming.






--- In squeak at yahoogroups.com, goran.krampe at b... wrote:
> Hi David!
>
> David wrote:
> [SNIP of ramblings :-) about documentation]
> > I'll apologize again for asking stupid questions like the ones above,
> > and now I'll sit down and be quiet.
>
> Those of us who have been in the community for some time, and I am not
> sure how long you have been here, tend to feel that people asking the
> community to "change" or to "Hey, you should do *this*!" don't really
> understand how this community works and generally gets little attention
> and might even piss people off. ;-)
>
> Let me be very frank and very disillusioned for a few seconds:
>
> 1. There have been A LOT of efforts starting to document Squeak. They
> all seem to "fade away". Nothing wrong with trying though - just don't
> think it hasn't been done before! Really. I am not kidding.
>
> 2. People do what they like to do. Coding is fun. Documentation is not.
>
> 3. Even though it is a harsh and perhaps annoying mantra - the "Ok, then
> why don't *you* do it?" logic still applies. Talking doesn't count for
> much.
>
>
> Ok, given the above - what can then be done that will actually have a
> slight chance to *succeed*? My take on this (which of course may be
> totally off) is:
>
> - Whatever you try to do, do it *yourself*. Don't try to talk others
> into it. "If you build it, they will come". This is at least my
> experience with SM.
>
> - Documentation is all about keeping it fresh. I have earlier proposed
> to try to bind documentation with the Unit tests. I still think it is a
> great idea (check archives to see what I mean). In other words, the docs
> must be tied to the image and tha packages, it can't live on its own. SM
> is of course a pillar to lean on in this case. IMHO class comments
> belong with the class - not on a swiki.
>
> - As with most things accepted in the community it very often comes down
> to good tools. SM is successful, but didn't render much interest until
> the Morphic package tool came onto the scene. BFAV has been successful
> becuase of similar reasons. The Magic Book concept (see Swiki - and how
> ironic? :-)) I sketched on earlier is based on this idea.
>
> So... in short:
>
> If *you* build *The Magic Book* tool and incorporate ideas to tie stuff
> with Unit tests or similar mechanisms that ensure things don't get stale
> - *then* something might happen. :-)
>
> My 2 cents, Göran




More information about the Squeak-dev mailing list