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