On Tue, Jul 29, 2003 at 08:39:49PM +0200, Andreas Raab wrote:
> > Rather than making yet another image-based registry, I think this 
> > would be a great use for the "annotations" that are part of the 
> > SMCard. After all, we *do* have a master registry for SM packages 
> > already.
> 
> Fine with me, I was just shooting for the simplest thing that could possibly
> work ;-) Considering that we have WorldMenu>>registerOpenCommand: it seemed
> to me that having WoldMenu>>registerPackageCommand: might just be the
> simplest solution of all.

Well, if we just need something simple that works, how about:

1) Class comments, at least for one or more classes that are obviously
associated with the SM package in question.

2) An agreed naming convention for a class side method category such as,
well, "documentation". This would be a place to put documentation.

3) An agreed naming convention for methods that provide documentation,
such as MyClass class>>squeakMapPackageInfo.

The default implemention of squeakMapPackageInfo could be:

Object class>>squeakMapPackageInfo
  ^ self comment

Anyone who does not bother with class comments would get a suitably
embarrassing "comment template" on SM. By writing at least one class
comment, a slightly less embarrassing message would be displayed on SM.
And anyone with sufficient motivation to provide actual documentation
could do so by hooking something useful into a #squeakMapPackageInfo
method.

I'm assuming that most SM entries will include some class that is
an obvious place to keep the documentation, and that we could invent
some simple way to associate the squeakMapPackageInfo for that class
with the SM package and make it available to Squeak Map browsers of
various sorts.

This would be practically zero extra work for anybody who documents
their classes. And I'm betting that someone who can't be bothered with
class comments is not likely to spend a lot of time updating Yet Another
High Tech Documentation Tool that is maintained separately from their
code base. I for one wouldn't do it.

Dave