Daniel,

Brief correction:
> - Various people say that the price of coordinating documentation
> development via the harvesting process is too high, 

I wouldn't say that the "price is too high". I simply think that we need
faster turnaround times. People shouldn't a) have to make up a CS and post
it to the list, b) have to fileIn a CS and then find what it actually
contains c) hope that this bit of documentation makes it at some point into
the image (BAD idea with packages!) d) have the ability to easily add links
that relate to some class. Like I was saying - the Swiki serves
documentation purposes quite well (though I wouldn't call it "democratic"
but rather "decentralized") and all that needs to be done to make it really
usable in the workflow is to link it right away with the places where people
are likely to go first. And that's the browser, and for classes in
particular it SHOULD be the class comment. (and of course, later we could
use this for methods as well, heh, heh ;-)

Cheers,
  - Andreas

> -----Original Message-----
> From: squeak-dev-bounces at lists.squeakfoundation.org 
> [mailto:squeak-dev-bounces at lists.squeakfoundation.org] On 
> Behalf Of Daniel Vainsencher
> Sent: Saturday, March 08, 2003 2:23 AM
> To: The general-purpose Squeak developers list
> Subject: Re: [DOCS] Swiki as a reference manual?
> 
> 
> 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
>