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
|