Good, thorough Smalltalk reference

On Tue, 17 Jan 2006 08:15:29 -0800, stéphane ducasse  
<[hidden email]> wrote:

> I do not really think that so much is changing.
>
> Traits: you do not have to talk about them
> method annotation: same here
> bugs fixes:
> MC and packages
>
> So for the good style part I do not see why squeak is changing.

Well, I think Traits are pretty important. They have the power to cause us  
to reform our thinking much in the way OO did. Maybe start with OO but  
ultimately work our way into traits.

The Tweak vs. Morphic thing is significant, too. People like to have, you  
know, user interfaces.<s> Someone here mentioned that some of the  
available stuff ends without ever leaving the transcript.

Oh, and filtered browsers--somebody mentioned the idea of seeing a limited  
subset of classes in the browser. One of my personal principles (when it  
comes to writing educational stuff) is to expose the reader to as little  
stuff outside of his level as possible. (This gets harder and harder the  
way most modern systems are headed. dot-NET is so loaded to the gills with  
crap, code-folding becomes an absolute necessity.) Anyway, it's a bit  
overwhelming to go into the Squeak browser and see everything ever written  
by anybody there.<s>

I agree entirely that good training material, tutorials and so on are  
vauluable documentation. So is pre-implementation doc explaining what  
the original intent was; I find it rather useful as a way to know  
when I'm finished and can bill the customer for one thing.

However, the original post was about *references for the classes*.  
That's a very different thing in a dynamic environment. I stand by my  
assertion that such doc should be a part of the system, included in  
the class and method sources. That *doesn't* mean it is the only  
place you get to see it! A documentation browser that gathers  
together all the class comments (reminder - we have this facility for  
having a comment attached to a class. Maybe some people should try  
writing some? Ever so helpful)  and related method comments (see  
previous parenthetical remark) is not likely to be a tricky thing to  
implement. Embarrassing, certainly, as we see how lacking and poor  
most commentary is.

In fact, an image running somewhere with all (plausible) packages  
installed and running some Seaside code could probably be a very good  
reference doc server.  It might even allow adding new doc and queuing  
it up for a quick review and release.

And don't forget that the comments attached to classes need not be a  
mere few lines of text! We can format it nicely, include doits (even  
click-on-me-do-its) for examples, have links to other classes and so on.

So. There's a few ideas to be getting on with. Come on, get moving!  
It's your system, start improving it!

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: LD: Lose Device

On 1/17/06, tim Rowledge <[hidden email]> wrote:
> In fact, an image running somewhere with all (plausible) packages
> installed and running some Seaside code could probably be a very good
> reference doc server.

The doc server bit I'd prefer in HV2, so everything is automagically
RESTful. It's easier to point people to the docs that way :)

Apart from that, it's a good idea. It'd be fun just to walk through
SqueakMap and install everything that says it can be installed in a,
say, 3.8 image...

On 17.01.2006 09:56, Julian Fitzell wrote:
>...

> If more of our code had good tests, a simple senders
> check would give you a very good idea of how to use the method and of
> whether it is public/private/etc.

What is the API?
Answering this question is very important for being able to define
dependencies between packages: private methods may change, but the
public ones have to be stable (however defined: there are different
compatibility levels) for being downwards compatible.

Currently the correct answer of this question needs category (re)naming
discipline of the developers.

Are there any tools, which help answering this question?
Something like profiling code and getting a statistic about which
methods in which classes are calling which other ones. For Blocks their
containing method may be of interest.


Stephan

>...

Hi folks!

I am not sure anyone is reading this thread anymore (pretty long),
especially since it is one of those yearly
let's-talk-about-documentation-discussions. :)

But I would like to remind you about an idea I floated a while back
(2003): The Magic Book.

First of all - regarding reference docs - as Tim says *external*
reference documentation for the classes is a no-no. And I am not saying
this because it would be bad to *have* :) - I am saying this because I
have been around long enough to realize it is a fruitless path for this
community to try *producing and maintaining it*. In short - there is no
way in HELL that such an external documentation would be kept up to date
with the code.

Reference documentation (class comments, method comments, method
categories etc) should be *part of the code* ensuring that it at least
stands a *chance* of being kept *somewhat* updated. In fact, again based
on years of experience, the only thing I personally ever demand of
codevelopers is that they maintain a reasonable class comment. I don't
even care about the style or format, just make sure it is there - at
least for the "important" classes.

That said - feel free to use Dandelion to generate external HTML (or
other formats) references in abundance, just don't think it will solve
our problem. Like this (I presume Dandelion was used):
http://www.oldenbuettel.de/squeak-doku/

Now, back to the Magic Book idea. The issue with documentation in
general is that it is not intrinsically *coupled* to the code. What I
mean is that you can change one (code or docs) without affecting the
other whatsoever. This is the basis of why docs always go stale - and
even if it isn't stale, I would never trust it *not* to be! And that is
an important observation. Even if there was reference documentation
generated in HTML for Seaside I would not trust it - because I know how
fast Seaside develops and I would never be sure it actually tells me the
truth.

The Magic Book idea came from the realization (after numerous rants to
get people to write unit tests from Stephane Ducasse :) ) that one of
the grand properties of unit tests - as being a form of documentation
(unit tests can often be used as example code) - is that they *are*
coupled to the code. If the code breaks the "external contract" the
tests break. And if the tests are modified - meaning that the "external
contract" is changed - the code possibly breaks. So a unit test can be
seen as an "external contract" of the behavior/API of one or more
objects.

Hmmmm... could we use this as a way of making documentation coupled too
perhaps? I think so. Imagine a book with chapters - each being a
tutorial, howto or introduction to a part of Squeak - and then imagine
every such chapter referencing one or more unit tests for the part it
describes. Each chapter typically describes how to *use* some objects -
in other words - it depends on the external behavior/API of those
objects. See how the unit tests come into play?

Now, if the unit tests for a chapter are green - everything is dandy. If
the tests go *red* (code was changed so that it no longer follows the
contract) or if the tests are *modified* (the contract was modified and
possibly the code too) we automatically flag the chapter as
Needs-review-and-possible-update. A flagged chapter may very well still
be valid - but at least this is a heads up to both readers and the
authors - it *may* have gone stale. And more importantly - if a chapter
is NOT flagged, then I would probably actually dare to trust it. :)

The actual book would imho best be written as a Morphic tool with the
ability to have the actual chapter contents loaded on demand in multiple
formats - HTML, wiki text, Morphic code, Morphic projects, whatever. And
each chapter could be a separate package on SM having separate
maintainers etc. It could spawn an external browser for HTML chapters,
it could show Morphic content directly, it could spawn an external
browser for wiki contents etc, etc.

Ok, this is probably the third time I describe this idea - it even has
its own page on the Squeak Swiki:
        http://minnow.cc.gatech.edu/squeak/3004

Perhaps it soon is time to actually implement it. :)

regards, Göran

PS. Anyone recall when people started writing reference docs for classes
on the Squeak Swiki? Or even further back, anyone recall the squeakdoc
swiki? (http://minnow.cc.gatech.edu/squeakdoc) or perhaps you recall...
enough. I guess you get my point. I am even "guilty" myself of such
fruitless endeavours - like the class comment challenge for example. I
am more and more certain that the "only" way to change our collective
behavior is through *tools*. Just look at SM, Monticello, SqueakSource
etc. Tools can be used to coach or provoke behavior. Postings to this
list typically can't... So over and out. :)

On Tue, 17 Jan 2006 23:08:52 -0800, <[hidden email]> wrote:
[on magic book]

Meh. There is something like that, I recall. When I read it, it was still  
usable, but awkward and a mess. The problem I see with it is that the  
documentation medium becomes subject to code rot on top of everything  
else. (We're not talking perfect solutions here, of course, and what I'm  
expressing is a matter of taste.)

Personally, I'm not all that interested in a reference. At the point  
you're really competent to use a reference, the various available Squeak  
browser tools are fine. Meaty tutorials on the big areas would give you  
the background you need to use them.

It's really not =that= big a deal. It's been done before. It's just been a  
while. I imagine Guzdial's books are still useful, even though they're,  
what, a decade old?

You know, I'm looking at Tweak and Croquet and neither of them seem to  
have moved much since last summer. Did I miss some ominous news?

At 21:14 17.01.2006, tim wrote:

I agree entirely that good training material, tutorials and so on are 
vauluable documentation. So is pre-implementation doc explaining what 
the original intent was; I find it rather useful as a way to know 
when I'm finished and can bill the customer for one thing.

However, the original post was about *references for the classes*.  
That's a very different thing in a dynamic environment. I stand by my 
assertion that such doc should be a part of the system, included in 
the class and method sources. ...

I agree wholeheartedly that the doc should be part of the system. Preferably, the program should be self-documenting.

Brains clearly differ. To me, the class browser is OK when I stuudy toy systems, but it is inadequate when I try to understand significant, complex systems. My brain just cannot bridge the chasm between class and method source code on the one hand and the objects and their interactions at run time. I believe I need code that is higher level than the class & method.

I have just completed my initial submission for an invited "expert voice" article for the Springer Journal on Software System Modelling:
BabyUML is a multi-paradigm approach where I
1)  separate the object space recursively into components; each component is an object that encapsulates its member objects. (Tweak!?)
2)  delare a conceptual schema for the member objects as a UML class diagram
3)  code the member object interaction with a sequence diagram for each provided operation.
4)  link the roles of the interactions to member objects with queries on the conceptual schema.
5)  code the internal behavior of the member objects with classes & methods in the usual way.

Complicated? Possibly. But I only intend to apply it when I must have it to master complex systems.

I have been in "writing mode" for quite some time now. I hope to return to "coding mode" quite soon. The goal is to make something that other people can play with.

All the best
--Trygve

--

Trygve Reenskaug      mailto: [hidden email]
Morgedalsvn. 5A       http://heim.ifi.uio.no/~trygver
N-0378 Oslo           Tel: (+47) 22 49 57 27
Norway

Blake wrote:

> You know, I'm looking at Tweak and Croquet and neither of them seem to  
> have moved much since last summer. Did I miss some ominous news?

Last I heard, which was a month or so ago, Croquet is still talking
about having a v1.0 release this summer!

*Lots* of work going on behind the scenes...

Bob

Hey Squeakers,

...& Göran

On 1/18/06, [hidden email] <[hidden email]> wrote:
> Hi folks!
>
> I am not sure anyone is reading this thread anymore (pretty long),
> especially since it is one of those yearly
> let's-talk-about-documentation-discussions. :)

Nice self-reference ;)

> But I would like to remind you about an idea I floated a while back
> (2003): The Magic Book.

[snip]
 [snip (color coded `pages' ``linked'' to test code to check the
environment, which does not break the ```book'')]

[snip]

Cheers for that message. I wasn't even on the Squeak Dev list back in
2003. Though I might have just been tinkering with it then, perhaps.
And this idea is so extremely cool, that I will have to give it a
proper ponder, since documentation is so important. General as well as
specific, seeing as I've been hacking PDFs to display on my ancient
Macintosh family of machines (1997 backwards...) - then, maybe a cool
feature of a Squeak Based PDF Reader would be its comprehending of
special objects, which were executable scripts. (this would then fit
in with the cool feature of OO environments, namely, Polymorphism).

So, that's the general idea GPL Copyright me. Implementation to come,
seeing as it's 2006 and I'm being overly optimistic.

Russell Hyer

On Wed, 18 Jan 2006 06:11:26 -0800, Bob Courchaine <[hidden email]>  
wrote:

> Blake wrote:
>
>> You know, I'm looking at Tweak and Croquet and neither of them seem to  
>> have moved much since last summer. Did I miss some ominous news?
>
> Last I heard, which was a month or so ago, Croquet is still talking  
> about having a v1.0 release this summer!
>
> *Lots* of work going on behind the scenes...

That's reassuring. I guess you can code or you can blog...