Let's see if I can summarize -
- Various people say that the price of coordinating documentation
development via the harvesting process is too high, considering that as
opposed to code, comments don't break people's image if a bad one is
accepted. Therefore, we need a lighter weight coordination mechanism,
and Swiki does that just fine for text. 
- This has the potential to make the process of doc evolution more
democratic/faster. 
- This requires some relatively simple changes -
* "update this comment in Swiki" for writers
* "update documentation from Swiki" for everybody else.
- Someone suggested that the latter be handled by autogenerating SM
bundles that include all the comments. This has some advantages - 
* we reuse an update mechanism, instead of adding YAUM.
* Putting all the documentation in a changeset makes it easy to review
using the file contents browser.
* It's very easy to release an image update every so often that installs
the current docs package. Maybe during releases.

I don't know, sounds just fine to me. But even better, it sounds like
the first part can be implemented as an SM package (for Class Comments
Crusaders, installing a package is not too high a price of entry), so we
don't have to accept it into the image, and the second part doesn't
require anything in the image, so I for one see no reason to discuss.
When a package appears on SM, those that want it, can use it.

Daniel

Douglas Brebner <squeaklists at fang.demon.co.uk> wrote:
> On Fri, 7 Mar 2003 21:57:59 +0100
> "Andreas Raab" <andreas.raab at gmx.de> wrote:
> 
> > Douglas,
> > 
> > > This will fail badly on machines without internet connections unless
> > > you somehow have them cache the whole lot in advance.
> > 
> > Oh, please. If you read my message you will see that I've taken this
> > into account already. To quote:
> > 
> > > E.g., write the class comment, accept, say "publish comment"
> >                                  ^^^^^^
> > 
> > That means you _first_ accept at which point the "normal thing
> > happens"(namely that the comment is present "cached" in the image) and
> > then you publish. The same thing could be done when you "update" the
> > documentation. Nothing will fail badly. It just works. If you're not
> > online the only thing you can't do is to update your documentation or
> > browse any of the links in it.
> 
> I was actually responding to this:
> >>> Simply declare the class comments to _be_ swiki pages (cached
> >>> locally if you want to) and allow everyone to change them at will.
> 
> which suggested to me that the comments would be stored on the swiki
> and only a cache (i.e. temporary) would be kept locally. I see now this
> wasn't what you meant.
> 
> [snip]
> > Like I said, people would _not_ need a full time connection. And using
> > "generated documentation" is questionable at best - if you read
> > JavaDoc stuff how much does it really tell you?! It's out of context,
> > no references to any discussions, examples, tutorials, whatsoever.
> > Swikis can provide all this and the only thing that remains to be done
> > is to link up the freakin' code with this documentation and integrate
> > it into the workflow!
> 
> I'm not talking about autogenerating documentation. I'm talking about
> automatically generating *packages* from the docs already on the web.
> 
> Pretty much what you suggest except you can update the in-image comments
> from SM in addition to directly via http.
> 
> And it need not only be comments which are packaged this way.
> 
> -- 
> Douglas