Hi Tim
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.
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.
I suppose that I am thinking of something different from the traditional 'comment'. By making a menu choice or button available from every possible component users can be taken contextually in to a structured wiki based comment/documentation/examples system. This would mean that users wanting comments and explanations can go looking for them very easily, but also that immediacy would be a great incentive for them and others to contribute by editing them or writing further material.
The problem with comments in the image currently is that they are put there by the programmer and so have to go through the same kind approval as the code. Also comments tend to be very specific (typically class or method based only). In practice there are many other system components and add-on packages that also need documentation to be available with much better immediacy.
Yours
Bob
PS I am getting postings directly from the archive and not via my email. I'm sorry the replies end up being an interesting mess - I'll see what I can do to find a better way.
______________
Documentation Suggestion
tim Rowledge tim at rowledge.org Sun Dec 30 06:46:38 UTC 2007 Previous message: Documentation Suggestion Next message: [ANN] ICal occurrence API Messages sorted by: [ date ] [ thread ] [ subject ] [ author ] Err, Bob, what email program are you using? It seems to have made a very confusing mess of the conversation thus far!
On 29-Dec-07, at 7:47 PM, Robert Hawley wrote:
>> what I meant here is a generic menu item or button so that >> every element >> is assumed to have documentation on the web-site. At the >> moment the >> comments get into the image with code - I am suggesting an >> external >> place where additional material can be added (including >> examples etc) >> much more easily and flexibly.
The cmd-6 weblink option I pointed out simply provides a way to have a URL in any text within Squeak; if you click on it Squeak tries to open the URL in your chosen web browser. Thus it is trivally easy to have any class or method comment contain a link to more detailed commentary, extended examples etc.
But crucially the mechanism is not even faintly the issue; the problem is getting the content out of people. Why, I've had to go to developers in the company of my old friend Mr BaseballBat to get comments out of them in the past!
tim -- tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim Fractured Idiom:- APRES MOE LE DELUGE - Larry and Curly get wet
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...
As you say yourself, comments for the actual code are only a small part of the problem.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Strange OpCodes: GSI: Garble Subsequent Instruction
squeak-dev@lists.squeakfoundation.org