Documentation, more, more

Lic. Edgar J. De Cleene edgardec2001 at yahoo.com.ar
Wed Sep 3 11:33:29 UTC 2003


On 02/09/03 07:58, "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
>>> 
>>> 
>>> 

leftie2100


I think you are unhappy with Squeak fellowship.

Facts :

1) Most of us are doing experiments and trying to learn a little about "The
Squeak Way"

2) Some of us are posting our finds in sites or in a swiki. Several  CD's
full of material can be found
(ftp://ftp.ira.uka.de/pub/squeak/cdrom/image.iso.gz is one)

3) None of us are collecting huge money with this (But we are having fun)


Last , You read something like "Don't ask what Squeak can do for you ...." ?

Hope you use your writing skills, cook a book , and get the fame and fortune
deserved to you .

>From Rosario , Argentina
Edgar 



More information about the Squeak-dev mailing list