Effective SM entries (was Proposal for
danielv at netvision.net.il
Wed Jul 30 10:56:50 UTC 2003
Just to clarify, my intent is very similar to what Andreas stated, in
that the documentation needs to be *obviously* available to the *user*
in some O(1) way - no search should be involved.
Another thing is that I think our first concern should be *user*
documentation, that covers the trivial initial aspects of how to get
some idea of what the software does, as opposed to code documentation.
The original impetus for this thread is really about the whole end to
end process of sharing software -
1. You need to hear that it exists
2. You need to find a packaged, recent version
3. Fulfill the dependencies
5. Figure out what button to press to get the initial GUI.
6. Understand how to operate it.
7. Start learning the architecture.
SM effectively solves 1, 2, 4.
SM 1.1 will help with 3.
If someone gets to 7, we've practically won already.
Our battle is for 5 and 6. The problem is that if the user cannot
estimate how long it will take him to understand a package, he may
decide out of hand that he doesn't have time to experiment today. This
is why I initially wrote that the initial documentation should be in the
SM entry in the description field. I accept Andreas' comment that the SM
entry can also merely mention that a how-to exists, but I think having
at least this is crucial, and requires no general agreement or code. If
you agree with the above, and care about people using your packages, fix
your SM entries.
[Andreas mention that SML is bad for loaded packages]
First, I've had suggestions before that SML should have a "loaded
packages" pane, though without very precise requirements for them. I'm
becoming convinced. OTOH, I think it is important to delimit what SM's
role is - I think it should be just about managing content installation
in the image. I say "content", because I don't think SM should be either
limited specifically to code, or specialized to a certain idea of code
(for example, SM should not know about MC). Systems that try to do too
many things, and are not clear about where their limits are tend to lose
focus of priorities, and not do even one specific thing well, and I'd
hate for this to happen to SM. The content installation space is big and
complex as is.
To get back to the issue at hand, I don't think SMs "installed packages"
pane should be the place where people expect to find the true contents
of their image. One reason is because people will still install stuff
using regular file ins, and specialized tools such as MC, and sometimes
it may not make sense to not this in SM. Consider code that doesn't yet
correspond to an SM entry to be an example.
I we do want some central point of access to everything I have installed
in the image, I think we should think about something new that will fill
that role. If we start with Andreas' idea of another dynamic menu, for
example, it might be a good idea for this to be a dynamic registry that
allows the registration of various kinds of objects - PackageInfos that
represent a specific code without other context, changesets that
represent raw fileins, SMEntries for SM installed stuff, MCPackages, and
One of the options that these entries could contain is documentation.
Andreas Raab <andreas.raab at gmx.de> wrote:
> Hi Göran,
> I think you missed the point of the proposal which was to use a Swiki entry.
> I'm sure the SM cache won't mirror the Swiki, would it? ;-) And yes, let's
> fix the UI thing - how about just making it so when we select "show
> installed packages" we actually _see_ the installed packages.
> - Andreas
> > -----Original Message-----
> > From: squeak-dev-bounces at lists.squeakfoundation.org
> > [mailto:squeak-dev-bounces at lists.squeakfoundation.org] On
> > Behalf Of goran.krampe at bluefish.se
> > Sent: Wednesday, July 30, 2003 12:47 AM
> > To: The general-purpose Squeak developers list
> > Subject: RE: Effective SM entries (was Proposal for
> > Morphicperformance-measurement enhancement)
> > Hi all!
> > First, as some of you know I am adding "resources" to SM1.1.
> > A resource
> > is either a simple String embedded inside the map (a so
> > called embedded
> > resource - meant to be used for meta information that is relatively
> > small and that needs to be available for all package
> > releases, not just
> > the installed ones. Think dependencies here...) OR a resource
> > reachable
> > with a URL.
> > Such resources can then be linked/associated with other objects in the
> > map (packages, packagereleases, categories etc).
> > "Andreas Raab" <andreas.raab at gmx.de> wrote:
> > > > A very simple solution: put the instructions on the Minnow
> > > > Swiki and give the reference in the description section of
> > > > the SM entry..
> > >
> > > I don't think that'll work too well. We already have a URL
> > which can be
> > > pointed at by the SqueakMap entry. Problems:
> > > * If people aren't online it doesn't work (such as me in an
> > airplane ;)
> > The new SM also boasts a proper cache. So you will be able to "mirror"
> > over the complete contents of SM to your machine. And the
> > master server
> > will also be such a mirror so you will not suffer from content on
> > servers not responding either. You will be able to have all package
> > releases and resources available locally.
> > > * The package loader (where it would be accessible) is very
> > hard to use for
> > > installed packages, e.g., when you open it, it shows exclusively the
> > > packages you _don't_ have and it's a pain to switch it so
> > that you see those
> > > that you _do_ have
> > We can easily fix that. A UI thing.
> > > * Practically speaking, using the package loader itself
> > would be a pain if
> > > all you want is to quickly navigate to a particular
> > tutorial/documentation
> > > (e.g., you need to open it, set it so it shows your
> > installed packages,
> > > click on the one you want, click on the URL link, close the
> > loader which is
> > > now probably behind scamper or so)
> > > * Editing a Swiki is a pain too (which is why I try to
> > avoid it) - I hate
> > > those tiny edit-boxes and idiosyncratic shortcuts
> > interspersed with weird
> > > html pieces (nothing against the collaborative aspects but
> > the usability of
> > > Swikis is very close to zero)
> > >
> > > I can probably come up with five other reasons why I don't
> > think that using
> > > a Swiki page is not a good idea when you want to work and
> > look for some bits
> > > of documentation, those are just a few which pop right into my mind.
> > >
> > > Cheers,
> > > - Andreas
> > regards. Göran
More information about the Squeak-dev