Stephane Ducasse <ducasse at iam.unibe.ch> wrote:
> Hi
> 
> I think that all the effort to **externalize documentation** are 
> doomed!!!!!

Yes, I posted my response before reading Stephane's and we are in
agreement here.

> Please consider to have documentation inside the image in a 
> ****synchronized*** manner.

Exactly.

> Documentation will be obsolete just after you wrote it. Believe me, I 
> worked in reengineering.
> 
> The only way to go for squeak is to write tests runnable executable 
> tests. Look at the great test suites for uuid. Or for digit 
> manipulation. I do nothing about bitshift but I can read the tests and 
> understand that ((1 biftShift: 100) biftshift: -100) = 1 is right.
> 
> Again you see that tests DOCUMENT the interface of the objects.

True and I agree. But I also think we need more "digestable"
documentation. Like an interactive book with an index, TOC etc.

> If you do not understand uuid like me just read them and you will see 
> that you will get a precise idea of uuid. So writing documentation as 
> SUnit is the only way to have documentation inside the image that will 
> be ***always in sync*** with the image and ***CRUCIAL*** those Tests 
> will support the possibility to change Squeak.

Yes, SUnit tests are by definition tightly linked with the code and will
simply break if they get "out of synch". True indeed. Perhaps then we
should base the interactive book that I am babbling about on the tests?
That sounds interesting.

If every "chapter" in the book are forced to be tied to SUnit tests for
the code they document then when the code canges (and the tests go
booom) we will immediately also see what parts of the book have gone
"stale".

What do you think Stephane?

> Note that the tests will also help the harvesters too.

Oh yes.

> So if you want to participate into documentation write tests in Sunit. 
> There is a tutorial on SUNit I translated for that purpose
> http://www.iam.unibe.ch/~ducasse/WebPages/Books.html
>  
> But the squeakers prefer to hack apparently. This is just too bad.

Hey Stephane. No need to sound so "hostile" - I am a Squeaker and could
take offense! ;-)

I agree with you on this but I also respect that people work in
different ways. Some of us are simply playing around, other use Squeak
for work or research etc. Different people, different backgrounds and
needs.

Having said that I still agree with you on the necessity of moving the
Squeak community into a more test-based "mode". And perhaps the best way
to do that is to take this into account when we reimplement the
Harvesting process.

If we integrate SUnit tests (like simply demanding them to be included
in FIXes for example) into the new tool for harvesting we might
eventually make ourselves use them more than we currently do.

regards, Göran