[DOCS] Swiki as a reference manual? (was: RE:[Squeakfoundation]Stewards and Squeak Packages)

goran.hultgren at bluefish.se goran.hultgren at bluefish.se
Fri Mar 7 19:09:16 UTC 2003


Hi all!

"Andreas Raab" <andreas.raab at gmx.de> wrote:
> > > Such a tool would perhaps (perhaps!) motivated people to write
> > > comments in the first place. 
> > 
> > Hmmm, well - why would a Swiki or a tool make it easier to 
> > write a class comment? It is dead easy already. Create a new
> > changeset, type in the class comment, send changeset to list
> > using the changesorter. Done.
> 
> It's at the list. Okay. Then we got to harvest it, review it, post it in the
> update stream. Then it's up to the next release before it takes effect.

Yes, I didn't mean to imply that we don't need a new Harvesting tool
(not necessarily driven by the mailinglist of course).
I was just wondering why typing in the class comment in a Swiki would
make it easier/better. Of course there are indeed some advantages - but
anyway...

> Honestly, the turn-around times for something as trivial as a class-comment
> are just HORRIBLE. Think about all the stuff you are mentioning, the
> overhead that gets added by harvesting, repackaging, updating. 

I agree. I also tried (once upon a time) to get people to do class
comments and *mark them* as being exactly just that.
Then it would make harvesting them a nobrainer.

> The point about "having a tool" would really be that you can write and
> publish a class comment while you're at it. E.g., write the class comment,
> accept, say "publish comment" and it's there. Accessible for everyone who
> wants to see if there's some more or updated information available.

True.

> The most important issue here is that there are no tools whatsoever in
> Squeak which link documentation with code. This is where all the
> documentation efforts break since once some documentation is up at a Swiki
> it soon becomes outdated. Why? Because the people who change the code need

Right.

> to search the entire Swiki to find that obscure place where the particular
> class is documented. We need a better style guide that allows for automated

Exactly. This is also how we (a few weeks ago) came up with the idea of
linking documentation to specific versions of unit tests.
But that is another thing.

> tools to view the documentation both in and out of Squeak. Since we use
> Swikis for this purpose already we have a pretty good feel how "outsider
> documentation" (by which I mean: documentation which hasn't been written by
> the original author) and to me, what's there is certainly better than what's
> in the image right now. So why not just go for the whole cake?! Simply
> declare the class comments to _be_ swiki pages (cached locally if you want
> to) and allow everyone to change them at will. You can still have all of the
> Swiki mechanisms (like locking pages etc) if you need to.

Yes, sure - could work.

Or we could - when we are rethinking how to manage Squeak anyway - think
about setting up some form of "distributed version control
Monticello/CVS/Arch-kindof super source code system" once and for all.
Seriously.

Class comments is just one piece of the game. Personally I think the
whole Harvesting business is flawed - shared distributed source control
would be best. On the other hand an image broken into separate packages
makes the Harvesting pain go away too.

Hmmmm. Perhaps best would be if we on SM could register info about how
the Steward/maintainer wants to accept feedback/fixes/enhs for his
particular package. One way could be "Send me changesets in email".
Another could be "Smack the changeset straight into my Monticello db if
you know the secret password". Etc.

If then the tools could (using PackageInfo or whatever) connect a
specific class with its package it could also look in the SM model and
decide what to do.

And of course - for class comments the tools could have an expressway
into the packages - if the maintainer thus wants.

Yadda, yadda....

> Cheers,
>   - Andreas

regards, Göran



More information about the Squeak-dev mailing list