Documentation [was: Morphic tutorial]

Richard A. O'Keefe ok at cs.otago.ac.nz
Thu Feb 13 23:41:40 UTC 2003


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!
I can throw Smalltalk code together that isn't totally horrible, sure.
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.

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.

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.  

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

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.

I once had a similar experience.  I was a judge in the local annual
programming contest.  The contestants had to use IBM Visual Age
(for C, C++, or Java).  I thought that I'd spend my waiting time
learning how to use it.  Well, I spent an extremely frustrating
hour trying to get the thing to let me create a source file with
hello world in it, and completely failing.  There was wizard piled
on wizard, a veritable confusion of conjurors, and they wouldn't let
me do the simplest thing.  And there were 3rd-year students powering
away as if it was easy.  Of course, they had seen the manual, and I
had not.  Now I _have_ a book about the system, and see what I did wrong
(practically everything), and the next time I'm faced with it I won't be
so helpless.

	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,
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.

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.

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.

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
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
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. 



More information about the Squeak-dev mailing list