On 5-Jan-08, at 7:40 PM, Robert Hawley wrote:
> I agree about the problem of getting people to write content.  That  
> is what I
> think is good about my idea of providing direct entry points to a  
> structured
> documentation site from the Squeak image.  It provides the kind of  
> immediacy
> that is currently lacking.

Well I can only hope you're right and my crumbly-old-bugger cynicism  
is wrong. But I  wouldn't bet more than a large latte on it....

>
>
> Rather than just allowing links to be added (as in the mechanism you  
> describe)
> what I am suggesting is that links should already exist in the Squeak
> image.
Hmm, one could make implicit links by deriving from the class/method  
names. That would provide for a simple, single, bit of documentation  
for each method (and by similar technique, class, perhaps, protocol,  
categroy and maybe package).

It would certainly be something of an improvement; I won't deny it. It  
ought to be fairly simple to extend the browser to try to load that  
doc from the web each time you look at a method - but make sure it  
doesn't slow down my browsing or I'll be after you with an elephant  
gun! - and to provide a way to submit doc as well.

Better yet, consider an idea that has been mentioned before and that I  
think is the 'real' answer;
http://lists.squeakfoundation.org/pipermail/squeak-dev/2007-September/120333.html

As you say yourself, comments for the actual code are only a small  
part of the problem.

tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Strange OpCodes: GSI: Garble Subsequent Instruction