On 27/12/2007, Robert Hawley <rhawley at plymouth.ac.uk> wrote:
Documentation Suggestion.
Can we have direct links from within the Squeak image from each class, method, project, category, package, (etc.,) into a user- editable documentation web-site?
The link part is easy - cmd-6 (on Mac, alt-6 on win32 and probably *nix) in a text editor opens a menu with several options including 'be a web URL link' so that you can include a link within comments. It also has linking to other methods, class comments etc.
> 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. Bob.
It would effectively be Squeak's own encyclopedia; similar to wikipedia. Structured documentation could be available with great immediacy, be developed incrementally and be subject to continual review and rewrite by the whole community.
Duane Maxwell tried to encourage just such an idea a few years ago and even set up a domain for it. I don't recall many people making the effort to provide any content. We don't even need a new site though; what is wrong with providing the doc on the swiki and linking to it?
> I think the structure of this would rather overwhelm the relatively > informal nature of the current swiki. I suggest a separate site; > maybe a separate site for every Squeak version. Some of the > material for the site could be automatically generated, so it may > not be solely dependent on added text. Bob
tim -- tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim Strange OpCodes: CDC: Clear Disks and Crash
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@rowledge.org; http://www.rowledge.org/tim Fractured Idiom:- APRES MOE LE DELUGE - Larry and Curly get wet
squeak-dev@lists.squeakfoundation.org
-
Robert Hawley -
tim Rowledge