[DOCS] Swiki as a reference manual?

Douglas Brebner squeaklists at fang.demon.co.uk
Fri Mar 7 21:59:49 UTC 2003


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



More information about the Squeak-dev mailing list