[squeak-dev] Documentation/Comment per package

Chris Muller asqueaker at gmail.com
Mon Jul 30 16:58:41 UTC 2012

> Subclassing PackageInfo just to add a comment seems wrong, and it is
> certainly not something that I would ever think of doing. Keeping the

My God y'all.  I never said the above.  Please read my words more
closely and stop putting words in my mouth.

I totally appreciate your point, which is the following:

      > a package has a comment, then the comment should be held by
      > the package object, in the same way that the comment for a class is held
      > by the class object.

That's fine but it ignores how the information would be used.  The
lifecycle of software consumption by Berts "normal" user is:

  Discovery --->  Installation --->  Exploration  --> Consumption

Discovery and Installation occur from the App Store (SM) -- BEFORE
someone is dealing with a single MCZ to even be ABLE to consume
package meta-data that may be there.

AFTER installation, the user is ready for _deeper_ Exploration, so I
think he's past the point of needing a general package comment.
Actually maybe a general package comment COULD be useful here since
most systems are made up of multiple MCZ packages and that would give
the user a feel for overall package-level responsibilities.  Still, my
guess is the user is usually looking to move forward with USING the
software for what it can do, caring less as much about
package-structure and how it works.

And this the stage where I think PackageInfo subclasses can be useful:
 The author can *introduce* the package to a newbie user in a way that
is specific to that package.  Things that move him *deeper* into the
software like #tutorial, perhaps.

So it's about providing the right information at the right time to
propel the user toward useful Consumption.

I'm not strictly opposed to your proposition, just trying to
understand the scenario in which your MCZ-level Package meta-data is
consumed, but since you won't say, it's hard to be supportive of any
"solutions" yet...

More information about the Squeak-dev mailing list