Effective SM entries (was Proposal for Morphicperformance-measurement enhancement)

Andreas Raab andreas.raab at gmx.de
Wed Jul 30 06:43:34 UTC 2003


David,

Let rephrase what I am trying to achive here: I am not interested in where
to put documentation (I don't care) but I am rather interested in HOW TO GET
TO IT.

All of what you propose has its merits and all of what you propose has been
done. There are classes which contain documentation (such as
AGenieIntroduction) there are categories which contain documentation (such
as in BalloonEngineBase class) there are methods containing documentation
(browse the implementors of #aComment) but that doesn't mean it's accessible
for people, that people know where to go looking for it.

What I want is a simple mechanism that people to hook up their documentation
right in the UI so that there is a simple, obvious way to provide varying
bits and pieces of information without requiring the user to "guess right"
at what the magic incantation is that will bring up the bit of information
which they are so urgently looking for.

So "simple" means really "simple to FIND by the user, and simple to USE by
the programmer". And while all of what you propose is certainly simple to
use, practice shows that it is typically not simple to find.

Cheers,
  - Andreas

> -----Original Message-----
> From: squeak-dev-bounces at lists.squeakfoundation.org 
> [mailto:squeak-dev-bounces at lists.squeakfoundation.org] On 
> Behalf Of David T. Lewis
> Sent: Wednesday, July 30, 2003 4:23 AM
> To: The general-purpose Squeak developers list
> Subject: Re: Effective SM entries (was Proposal for 
> Morphicperformance-measurement enhancement)
> 
> 
> 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
> 
> 



More information about the Squeak-dev mailing list