Hi

I think that you are mixing things there. If you want to learn squeak  
read a book.
If you want to use for educators go to squeakland.org, by the book of  
kim or wait a bit to buy my new book.



Now I think that even if squeak would have a good technical  
documentation you would complain
that this is not for newbie. So what can I say?

If you do not understand this tutorial (or the columns I wrote in  
french) this means that you should
read my book first on teaching novices.

http://www.iam.unibe.ch/~ducasse/WebPages/Programmez/OnTheWeb/ 
SUnitEnglish2.pdf

My anwser was about providing a good documentation to Squeak  
*****programmers*****.

stef


On Tuesday, September 2, 2003, at 12:58 PM, leftie2100 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
>>>
>>>
>>>
>
>
>