I agree entirely that good training material, tutorials and so on are  
vauluable documentation. So is pre-implementation doc explaining what  
the original intent was; I find it rather useful as a way to know  
when I'm finished and can bill the customer for one thing.

However, the original post was about *references for the classes*.   
That's a very different thing in a dynamic environment. I stand by my  
assertion that such doc should be a part of the system, included in  
the class and method sources. That *doesn't* mean it is the only   
place you get to see it! A documentation browser that gathers  
together all the class comments (reminder - we have this facility for  
having a comment attached to a class. Maybe some people should try  
writing some? Ever so helpful)  and related method comments (see  
previous parenthetical remark) is not likely to be a tricky thing to  
implement. Embarrassing, certainly, as we see how lacking and poor  
most commentary is.

In fact, an image running somewhere with all (plausible) packages  
installed and running some Seaside code could probably be a very good  
reference doc server.  It might even allow adding new doc and queuing  
it up for a quick review and release.

And don't forget that the comments attached to classes need not be a  
mere few lines of text! We can format it nicely, include doits (even  
click-on-me-do-its) for examples, have links to other classes and so on.

So. There's a few ideas to be getting on with. Come on, get moving!  
It's your system, start improving it!

tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Strange OpCodes: LD: Lose Device