[squeak-dev] [documentation] HelpSystem, revision control, and process

Casey Ransberger casey.obrien.r at gmail.com
Fri Apr 30 23:27:54 UTC 2010


Ken,

Yeah; it supports keeping documentation in methods. Andreas added a patch
that makes it easy to edit a help topic in a workspace, and it recompiles
the source method automatically when you accept. So we should be able to use
our revision control on our docs (which has proven very useful for me in the
past.)

The reason I recommend using Trunk is so that folks don't need to switch
contexts to add documentation. I also think that having a help system in a
standard image is a good idea. I would expect to modify
Smalltalk>>unloadAllKnownPackages to unload it, as I don't believe such a
system belongs in a core image at all.

These are just my feelings, though. I do appreciate your caution about
adding bloat to Trunk; I cringe a little suggesting it, but I still think
it's a good idea. Would you be willing to wait a bit, and gauge the broader
community's opinion before making a decision about this? I'm really hoping
to have a few more people weigh in on pros and cons. That said, I really do
respect your opinion on the matter, and a separate repo on
source.squeak.orgwould be fine (maybe
source.squeak.org/help).

One thing I would like to do is get a quick gauge of the complexity of
HelpSystem so people can get a sense of how much I'm really talking about
adding. I'll try and find some time to do that in the next day or two. Good
time for me to read el bloggo de Raabo:)

On Fri, Apr 30, 2010 at 3:35 PM, Ken Causey <ken at kencausey.com> wrote:

> > -------- Original Message --------
> > Subject: Re: [squeak-dev] [documentation] HelpSystem, revision control,
> > and  process
> > From: Ian Trudel <ian.trudel at gmail.com>
> > Date: Fri, April 30, 2010 5:20 pm
> > To: The general-purpose Squeak developers list
> > <squeak-dev at lists.squeakfoundation.org>
> >
> >
> > Quick question, Ken (and Casey).
> >
> > How will the core related documentation will be transfered to the core
> > image assuming what you wrote will define our process? HelpSystem
> > includes classes and methods comments.
> >
> > Ian.
>
> Well, this is exactly why I have that leading sentence. ;)  I have no
> idea how content distribution (which is what I assume you are asking
> about) is meant to work in HelpSystem.  I have to assume from Casey's
> question that it can be distributed in a mcz.  As such it can be
> retrieved via any method desired and from any location.  What triggers
> loading any particular content?  I don't know, is there meant to be a
> catalog something like SqueakMap or Package Universes?  Or is help for a
> particular package an optional dependency?  Clearly, as I stated, I have
> no end of questions.
>
> Ken
>
> > 2010/4/30 Ken Causey <ken at kencausey.com>:
> > > I haven't been following the HelpSystem discussion very closely so
> there
> > > is no limit to what I don't know on this subject.  That said I would be
> > > perfectly happy setting up a HelpSystem repository on
> source.squeak.org.
> > >
> > > In general I feel we need to start limiting the contents of the trunk
> > > repository to those packages that compose 'core' Squeak and start
> > > considering add-ons used to build 'basic' Squeak as separate packages
> > > installed into 'core'.  I'm assuming that HelpSystem is something we
> > > would want to include in a 'basic' image, but not a 'core' image.  (Of
> > > course a 'core' ZIP might include ready to load optional packages
> > > including HelpSystem.)
> > >
> > > Ken
> > >
> > >> -------- Original Message --------
> > >> Subject: [squeak-dev] [documentation] HelpSystem, revision control,
> and
> > >> process
> > >> From: Casey Ransberger <casey.obrien.r at gmail.com>
> > >> Date: Fri, April 30, 2010 3:22 pm
> > >> To: The general-purpose Squeak developers list
> > >> <squeak-dev at lists.squeakfoundation.org>
> > >>
> > >>
> > >> Folks,
> > >>
> > >> I'd like to get a process going around HelpSystem. It doesn't have to
> be a
> > >> perfect process. We can tweak it as we go.
> > >>
> > >> How do people feel about having help in the Trunk? It'll allow us to
> > >> document things right along side of our software development.
> > >>
> > >> One thing worth noting: we can have our HelpSystem "book" in Trunk
> without
> > >> necessarily having HelpSystem itself in the Trunk; however, if we do
> it that
> > >> way, we run the risk of changes in HelpSystem on SqueakSource making
> our
> > >> help content impossible to load. I think having both in the Trunk is a
> > >> really good idea.
> > >>
> > >> If folks aren't comfortable with having some documentation and
> HelpSystem in
> > >> Trunk, I'd like to propose opening up a 'docs' SS repository on
> > >> source.squeak.org. We'd lose the ability to track the evolution of
> our docs
> > >> in the context of the evolution of Squeak, but we'd still have the
> keys to
> > >> the kingdom (license, code, content.)
> > >>
> > >> I'd rather not go with squeaksource.com, as I'd like to think that
> our docs
> > >> should live with the other things on squeak.org.
> > >>
> > >> As always, feedback is appreciated.
> > >>
> > >> --
> > >> Casey Ransberger<hr>
> > >
> > >
> > >
> >
> >
> >
> > --
> > http://mecenia.blogspot.com/
>
>
>


-- 
Casey Ransberger
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20100430/96489d6c/attachment.htm


More information about the Squeak-dev mailing list