Documentation [was: Morphic tutorial]
goran.hultgren at bluefish.se
goran.hultgren at bluefish.se
Fri Feb 14 09:45:34 UTC 2003
"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
> 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.
> 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
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.
More information about the Squeak-dev