Documentation, more, more

leftie2100 leftie2100 at yahoo.com
Tue Sep 2 10:58:08 UTC 2003


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
> >
> >
> >



More information about the Squeak-dev mailing list