Hi Leftie, everybody.

I think you're all right, but talking "at" each other. Seemed to me the
most important thing is to make sure that the Swiki references
documentation in a way that is effective for newbies. The reason the
Swiki is important is that it is visible and easy to keep updated. The
problem with the Swiki is that it has some repetition and incoherence.
That is not that hard to fix, if someone is willing to read everything
available on a specific topic and make small integration changes so that
ends up more coherent than it was.

Leftie, if you as a Squeak newbie feel that you aren't well served by
the existing stuff, you're probably right - it is after all your
perspective. But also, because it is that, we can't really solve the
problem without your help, for the simple reasons that that perspective
is no longer available to most of us (or, due to unfamiliarity with
alternatives, maybe it never was). The best thing that you could do to
improve the situation is to try and read everything you can find using
the Swiki, integrate what's there, and ask on the list about stuff you
don't find. Anything you feel lacking is probably out there somewhere,
and someone here will be able to point you at it.

I tend to agree with you that the kind of documentation that is most
important for newbies is probably practically best kept as "dead text"
and won't require too much updating. I agree with Stef et al's point
about documentation going stale in the context of framework specific
documentation. Of course both are needed, and it makes sense that they
might be best served by different means.

Are you interested in helping improve the documentation situation for
newbies?

Daniel

leftie2100 <leftie2100 at yahoo.com> wrote:
> Stephane,
> 
> Without intending it, I do believe you just proved everything I was
> attempting to describe about the way the squeak developer community
> acts toward educating new users to squeak.
> 
> Now, I personally don't know enough about "tests" to know if they are
> a good educational tool or not. However, to find out if they are, you
> expect me to search the entire squeak mailing list archive, find a
> tutorial on a web page that seems to house books, not tutorials (the
> particular tutorial might be located in the pages of one of the
> books...I'm not sure... I would have to learn  French to find out for
> sure), and then once I know what tests are and how to use them, guess
> which ones I should learn in what order to learn squeak properly.
> 
> That's not a user-friendly educational environment. I pretty much have
> to already know whatever subject I need to learn to have enough
> background to figure out how to just find the necessary resources I
> would need.
> 
> Why are python and ruby growing like weeds right now? In a large part,
> because they reach out to new users and try to help them become
> educated in using those tools in the most "newbie-proof" manner
> possible. They both have full intro textbooks that can be downloaded
> as an introduction to the language. You don't have to have the "most
> up-to-date" version of squeak making a intro text obsolete... just
> have links to the version used in the text next to the links where you
> get the text. The intro to a newbie doesn't have to have all the bells
> and whistles. The text would only have to be updated every couple of
> years that way. It doesn't have to be a textbook,either. It could be
> the equivalent of a big help file or tutorial software. However, it
> does need to be structured in a way that a person moved from one
> subject they need to learn to the next until they were capable of
> programming at a minimum level of competancy.
> 
> 
> 
> 
> 
> --- In squeak at yahoogroups.com, Stephane Ducasse <ducasse at i...> wrote:
> > Hi all
> >
> > I think that the best, more efficient way of providing documentation
> > about Squeak is to write simple tests representing scenario. We cannot
> > afford having people write documentation that will get obsolete as soon
> > as we change something. because Squeak is not a frozen framework but
> > something that is moving fast. So all your effort to externalize
> > documentations in non executable way are doomed to fail and frustrate
> > you.
> >
> > Tests are the only way to go, sorry if this is hurting. But tests are
> > coooooooool, they provide you this guts feelings, "YES it works. I'm
> > sure it works".  You have to experience that by yourself because this
> > is personal but this is a so good feeling.
> >
> > With test
> > 	- your documentation is always in sync with the code. Just press the
> > button and if it is green you 	are sure,
> > 	- this way we can change the system without fear to breaking something
> > that would stay not 	identified,
> > 	- tests represent your trust in the system,
> > 	- Everybody even newbies can write tests
> > 	- If you write tests lot of people will enjoy review them and include
> > the into squeak
> >
> > Tests are like solar energy, they ensure that we will be able to fix
> > stuff in the future. Ok they cost a bit more at the beginning but they
> > provide a lot more . Developing without test is fun but like nuclear
> > energy it endangers our future.
> >
> > Look at the tests provided for the UUID to understand what I mean.
> >
> > 	- daniel wrote a small tests to show how easy is to write tests.
> > Daniel will post that soon
> > 	after his trip back from ESUG
> >
> > 	- If you want to know more about tests
> > 		- browse my emails in the archive
> > 		- read the tutorial on SUnit available at:
> > 			http://www.iam.unibe.ch/~ducasse/WebPages/Books.html
> >
> > Stef
> >
> > Just a real story that happens to me yesterday.
> > I was coding something and nearly there without any tests because I'm
> > lazy and this was trivial when I realized that a special case could
> > break everything I did. This was boring, frustrating and too complex
> > after a day of work. So I started to write 4 tests. It took me around
> > one hour really slowly to pay attention to have a simple scenario for
> > each of my cases. Then I recoded everything running the tests in 15
> > minutes.
> > At the end all the tests passed green and I was done. DONE with the
> > feeling YES it works I can go home coooool and sure that I did it
> > right. During the night I run my application to extract a big db and it
> > worked. Now if it happens that I still have a bug, I will start first
> > writing a test and fix it.
> >
> >
> >
> >
> > On Monday, September 1, 2003, at 01:21 PM, Gary Fisher wrote:
> >
> > > 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 y...>
> > > To: "The general-purpose Squeak developers list"
> > > <squeak-dev at l...>
> > > 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
> > >
> > >
> > >