Documentation, more, more

Stephane Ducasse ducasse at iam.unibe.ch
Tue Sep 2 08:18:13 UTC 2003


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 yahoo.com>
> To: "The general-purpose Squeak developers list"
> <squeak-dev at lists.squeakfoundation.org>
> 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