Documentation Suggestion

Robert Hawley rhawley at plymouth.ac.uk
Sat Dec 29 00:03:34 UTC 2007


Hi

I am not sure if my suggestion was made very clear - I was not thinking of google searches when suggesting this.

The suggestion proposes a simple route for the community to be able to write better documentation and explanations.

I envisage a web-site pf pages of which can be reached via a simple contextual click or menu selection from with the Squeak image.  The pages would be
editable (like wikipedia) and would have scope to provide much better explanations than the comments found in the image.  Method and class comments are generally
very primitively written and do not hyperlink to better explanations - comments in the image are bound to the 'approved' code, are too inflexible, vary in stye and utility,
and cannot easily and globally be improved. A web-site would give much more flexibility for improving the documentation.

A structured web-site could do more than just reflect the components in the image - it could also serve as a place where higher-level explanations and commentary
can be also be provided. As such, the repository I am suggesting would make the whole of Squeak much more accessible.

Yours

Bob



_______________________
>
Damien Pollet damien.pollet at gmail.com
Thu Dec 27 15:03:01 UTC 2007
Previous message: Documentation Suggestion
Next message: Documentation Suggestion
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
I have been thinking of doing that, at least to get google to index
smalltalk code, so that people can see what that looks like without
loading an image first. As far as structured documentation is
concerned, you already have that from within smalltalk, when there are
class or method comments.

There is already code in Pier to export comments as LaTeX or HTML
code, I think that's what Lukas used to generate part of his thesis.
SqueakSource has a code browser but it's not bookmarkable and I don't
think it's indexed by search engines.


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?
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.
>
> If there is existing discussion on this idea then it would be useful to have pointers to it.  If it has not been much discussed before then I would suggest that this is a
possibility worth exploring.
>
> Yours
>
> Bob
>
>


--
Damien Pollet
type less, do more [ | ] http://typo.cdlm.fasmz.org
.



More information about the Squeak-dev mailing list