"Richard A. O'Keefe" <ok at cs.otago.ac.nz> wrote:
> I wrote:
> 	> The next time someone says "let's make a Swiki page to talk about
> 	> documentation" I'm going to vomit.
> 	
> goran.hultgren at bluefish.se wrote:
> 
> 	Well then, Mr O'Keefe - why don't you help out then? You are a very
> 	competent Squeak programmer - perhaps you could help us realize the
> 	"Magic Book"? And if you don't have the time to help then... well.
> 	
> A very competent Squeak progammer?  Me?  You must be joking!

No, I am not. I have read many of your posts and there are few with your
knowledge of Smalltalk and thus also Squeak. I am confident that you
could produce good Squeak code.

I mean hey, you are obviously in another division than me - and even I
can whip up code that people like (SM). ;-)

> I can throw Smalltalk code together that isn't totally horrible, sure.

Probably the understatement of the week. :-)

> But I've been using Squeak since 2.7 and I have never come across any
> programming language or system that can humiliate me quite as thoroughly
> as Squeak does.

No? I feel quite the opposite.

> To put it bluntly, the parts of Squeak that I *could* document
> are precisely the parts that don't *need* all that much documentation
> because they are already explained in the Goldberg et al coloured books
> and LaLond's "Inside Smalltalk".  In fact, that's precisely how come I
> *do* understand them.

Nah, I don't agree. There are tons of basic Smalltalk classes in Squeak
that are in desperat need of good comments, unit tests, examples etc. I
mean, jesus - do we really think that Collection should only have a
oneliner as class comment?! I don't.

> Of course I am exaggerating a little bit.  The browser in Squeak 3.4 has
> a lot of nice features that aren't in those books, but it is close
> _enough_ to the old ST-80 browser that I could start from a knowledge
> of that and move forward.
> 
> About the only thing that's not in those books that I think I could
> document usefully is change sets.  It took me a fair bit of cautious
> experimentation to learn that much.  

Well, there you go. :-)

> Now that there are DVS and SAR thingies, I feel as though I am a total
> newbie again.

But those things are IMO much easier to understand than the wonderful
ChangeSet beasts.

> It is PAINFUL to feel stupid and dumb and helpless when you are used
> to feeling clever and competent, especially when the language itself
> is so simple.

True indeed.

[SNIP]
> 	Squeak suffers from lack of a good multi developer source
> 	management system (which should of course include documentation)
> 	and lacks a good process for dealing with it (Harvesting has
> 	great problems).  We all know this painfully well.
> 	
> And if anyone doesn't, try submitting a fix and see the bug still there
> several releases later....
> 
> However, this really isn't the issue.  Source management has nothing
> to do with it.  Morphic and EToys have been around for a long time,

Well, in parts I agree with you - but frankly I *do* think it is one of
the issues.
When people don't have a common "workplace" stuff gets scattered about,
duplicated, lost, stale etc. So IMO it is actually one of the root
problems. Not the only problem though.

> and while I'm sure there's a lot of detail going on under the hood,
> there's a whole lot of stuff about how to USE these things which hasn't
> changed all that much.  The main revolution, which rendered obsolete
> much of what little documentation there was, was the introduction of
> layouts, and despite reading the tutorial project, I must say I still
> don't really understand the choices or how the programming of layouts.

Haven't used them so I can't say.

> Documentation does not have to be bulky.  The documentation for the
> Interlisp-D graphics system was two slim chapters, but after two days
> reading those chapters and one day of trying things out, I was able to
> actually construct GUIs in Interlisp-D.
> 
> 	But we are aiming to solve these problems. Harvesting will change
> 	dramatically once we have the new tools set up for that. SqueakMap has
> 	already changed a lot. And the Magic Book could do the same for
> 	documentation inside the image.
> 	
> 	So while I can sympathize with your comment (good knows I can)
> 	it is still a rather stupid comment to post in an open source
> 	project.  In My Very Humble Opinion.
> 
> Given that people have been talking about talking about documentation	
> for about as long as I've been using Squeak, and that very little usable
> documentation has actually resulted from all this talking about talking
> about documentation, it is not at all a stupid comment.

Well, perhaps it was the tone I didn't like. It doesn't matter. I do
agree with the feeling but I don't want to discourage those that now are
digging in and really trying. 

> I am a happy user of several open source projects and have made minor
> contributions to a couple of them.  Mostly they come with at least
> a hundred pages of printable documentation.  One of them came with
> about a thousand pages of printable documentation, much of it automatically
> extracted from the sources.  To take just one example, the documentation
> that came with my copy of Lout is VASTLY better than the documentation
> that came with my copy of Microsoft Word.

Yes, I have used Lout - really nice package. And I agree - those manuals
are simply beautiful.

> I think maybe this very feeling "oh, we have to wait until we have
> better tools and processes because documentation is a multideveloper
> issue" is part of the problem.  The best documentation comes when one

Well, I am not arguing for us to wait - quite the opposite. But I do
argue for also bringing about better tools because it will make a huge
difference in the long run. I mean, that argument could as easily have
been made against doing SM too you know. And I hope you agree that SM
has turned out to something really good, right?

> person is in charge.  If the documentation doesn't fit coherently in
> one person's mind to start with, chances are it never will.  Others

Also probably true.

> can help with editing, proof-reading, example construction and checking.
> *ONE* person who understood bookmorphs thoroughly could document them
> well enough to be useful.
> *ONE* person who understood GeeMail thoroughly could document it well
> enough to be useful.
> 
> But for each topic, it has to be someone who understands that topic
> pretty well, NOT someone who is screaming for documentation because
> they feel dumb and helpless without it.  Suggesting that the ignorant
> should be the instructors is not, perhaps, the cleverest suggestion
> to post in an open source project's mailing list.

This last paragraph feels like the "punchback" I was waiting for. ;-)
But if it is and you are implying that I have said that - then I would
like a quote, because I can't remember ever saying that.

But that doesn't mean beginners can't help us out - I think they can,
and in many different ways.

regards, Göran