Documentation Suggestion

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

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 <[hidden email]> wrote:

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

> SqueakSource has a code browser but it's not bookmarkable and I don't
> think it's indexed by search engines.

Philippe made some extensions to SqueakSource so that it can be
indexed by google. We don't know why it doesn't properly work,
probably the search engine thinks it is fraud by the big duplication
with all the different versions of the same code.

Lukas

--
Lukas Renggli
http://www.lukas-renggli.ch

On Thu, 27 Dec 2007 18:30:12 +0100, Lukas Renggli wrote:

>> SqueakSource has a code browser but it's not bookmarkable and I don't
>> think it's indexed by search engines.
>
> Philippe made some extensions to SqueakSource so that it can be
> indexed by google. We don't know why it doesn't properly work,
> probably the search engine thinks it is
> fraud

LOL :)

> by the big duplication
> with all the different versions of the same code.

I'm relatively good at search engine optimization (no, not the buzzwords  
business but the server technical side) because of customer demand (sites  
with sometimes > 10,000 pages). Could you/Phillippe post some example URLs  
of contents which ought to be indexed. Can give it a try and report what I  
find.

/Klaus

> Lukas
>

Yeah in fact I'm not sure google indexes all versions of repositories
with web frontends.  For people I guess it would already be useful if
the latest version of each package was indexed.

On 27/12/2007, Lukas Renggli <[hidden email]> wrote:

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

On Thu, 27 Dec 2007 19:24:17 +0100, Damien Pollet wrote:

> Yeah in fact I'm not sure google indexes all versions of repositories
> with web frontends.  For people I guess it would already be useful if
> the latest version of each package was indexed.

I think that *all* the project pages are indexed (IIRC that was what  
Phillipe made work), see

-  
http://www.google.com/search?q=SqueakSource+project+page+%22.mcz%22+site%3Asqueaksource.com

But the .mcz files listed on those pages don't turn up in search results  
(or I have just not found a way to get results with .mcz or .zip files  
listed using google with site:squeaksource.com).

/Klaus

> > by the big duplication
> > with all the different versions of the same code.
>
> I'm relatively good at search engine optimization (no, not the buzzwords
> business but the server technical side) because of customer demand (sites
> with sometimes > 10,000 pages). Could you/Phillippe post some example URLs
> of contents which ought to be indexed. Can give it a try and report what I
> find.

http://www.squeaksource.com/robots.txt
http://www.squeaksource.com/sitemap.xml.gz

Note that the directory listing produces a slightly different result
when being visited by a GoogleBot.

Lukas

--
Lukas Renggli
http://www.lukas-renggli.ch

On Thu, 27 Dec 2007 20:13:35 +0100, Lukas Renggli wrote:

These look indeed reasonable except response header expiration date of  
/robots.txt and .mcz files (how would anybody reset that date? seems to be  
impossible and perhaps *this* looks like fraud to them; I personally never  
go past 12 months; your to be sure that some day it's me who's back in  
control).

And then the absence of last-modified field in response headers. The  
latter shouldn't be that hard to add, so that crawlers don't have to work  
on assumptions and webmaster has a bit more control on content  
negotiation. *This* is the hot-spot (and not an expiration header past  
funeral date) when you don't want them to re-index but later perhaps have  
file format/contents/organizational/conceptual change which are unable to  
imagine now.

Also the project pages have expiration a minute or so from date header,  
why would anybody follow their links?

Well then, tried some of the project pages linked from sitemap.xml but  
Google is by no means interested "We're sorry, but there isn't enough text  
on this webpage; at least a few paragraphs are necessary to provide  
results. You can try entering a different URL, or check the box labeled  
'Include other pages on my site linked from this URL'."

There ya go, another incarnation of the Squeak+Documentation problem  
(seemingly many (most?) authors don't write something up on their  
SqueakSource entries which then can be put onto the crawler's project  
pages).

This *can* be the reason (but perhaps also the content type of the .mcz  
files).

How about putting at least "Squeak, Squeaksource, <project name>, <tags>"  
into html keyword meta data on project pages.

> Note that the directory listing produces a slightly different result
> when being visited by a GoogleBot.

What's in that? I can make more mistakes when attempting to find out than  
you can imagine. Could you post an example generated by the software from  
the Regex project (which Google doesn't like to index). Also, are there  
differences in response headers.

/Klaus

> Lukas
>

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
.

>
> On 27/12/2007, Robert Hawley <[hidden email]> 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.

>> 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?

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: CDC: Clear Disks and Crash

>
> 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:
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; [hidden email]; http://www.rowledge.org/tim
Fractured Idiom:- APRES MOE LE DELUGE - Larry and Curly get wet

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:
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.html

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

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: GSI: Garble Subsequent Instruction