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

Andreas Raab andreas.raab at gmx.de
Fri Mar 7 16:33:33 UTC 2003


> > 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.

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. 

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.

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
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
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.

Cheers,
  - Andreas



More information about the Squeak-dev mailing list