Smalltalk › Squeak › Squeak - Dev

Documentation Team

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

27 messages Options

Michael Haupt-3

Re: Documentation Team

Hi,

On Wed, Aug 25, 2010 at 8:23 PM, Jecel Assumpcao Jr.
<[hidden email]> wrote:
> One important feature for the documentation is to make it more easily
> available outside of Squeak. I don't like to write the same thing twice,
> but imagine that we could create a doc.squeak.org site running a fully
> loaded image and automatically exporting all the documentation in a form
> that people and web crawlers can use.

I think I recall that idea - didn't it occur first in an on-list
conversation between me and Ian Trudel? It's certainly not a new idea,
I'm sure of that.

I also recall that, when running for the board, I had the term
documentation painted all over me, and there were some ideas like
these:
* have HTML (or something) documentation automatically generated from
a documented image
* have special repositories for documentation (à la /trunk, /inbox:
/docs), writable for everyone
* ...

It should be in the archives.

Best,

Michael

Hannes Hirzel

Re: Documentation Team

In reply to this post by Tobias Pape

Hello Tobias,

On 8/26/10, Tobias Pape <[hidden email]> wrote:

>
> Am 2010-08-26 um 07:26 schrieb Hannes Hirzel:
>
>> On 8/26/10, Casey Ransberger <[hidden email]> wrote:
>> ....
>>
>> CURRENT ACTION FOCUS
>>>
>>> That said, I think the web facing docs are a lower priority than gettin
>>> some
>>> good documentation written.
>>>
>> I agree with the priority setting. We need to produce more
>> documentation _within_ the image.
>>
>> And as the tool to stay organised we have chosen Mantis.
>>
>> Generating a web version of it (something like Javadoc) - I am pretty
>> sure we will find somebody to do it. Similar things have been done in
>> the past.
>
>
> Reading that, can we interface http://soek.goodies.st/ somehow?

Thank you for providing the pointer. Was this the web interface we
were talking about in April this year?

As a whole I favor focusing on let's say getting some of the class
comments fixed before exposing the image to the web.

However a web documentation is something useful for people coming from
Java for example as they are used to JavaDoc. As soon as they have
learned navigating around in a Smalltalk image there is less a need
for it.

Another thing: It would be good to have a huge alphabetical list with
all method names and their class comments to analyse with standard
Unix tools (e.g. grep).

And the same thing for all categories and classes and class comments.

And classes ordered alphabetically with their comments.

Just three huge files.

This would make feel people coming from other environments more
comfortable at the beginning.

Which are the Smallltalk code snippet to do this?

--Hannes

Frank Shearar

Re: Documentation Team

In reply to this post by Tobias Pape

On 2010/08/26 08:29, Tobias Pape wrote:

>
> Am 2010-08-26 um 07:26 schrieb Hannes Hirzel:
>
>> On 8/26/10, Casey Ransberger<[hidden email]> wrote:
>> ....
>>
>> CURRENT ACTION FOCUS
>>>
>>> That said, I think the web facing docs are a lower priority than gettin some
>>> good documentation written.
>>>
>> I agree with the priority setting. We need to produce more
>> documentation _within_ the image.
>>
>> And as the tool to stay organised we have chosen Mantis.
>>
>> Generating a web version of it (something like Javadoc) - I am pretty
>> sure we will find somebody to do it. Similar things have been done in
>> the past.
>
>
> Reading that, can we interface http://soek.goodies.st/ somehow?

By the way, Soek's broken at the moment:

<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Error</title>
</head>
<body onkeydown="onKeyDown(event)" onload="onLoad()">
<h3>Transport<http> failed - Wrong response status line: PROPFIND
/Soek/Launcher/ HTTP/1.1</h3>
</body>
</html>

frank

Tobias Pape

Re: Documentation Team

Am 2010-08-26 um 09:41 schrieb Frank Shearar:

> On 2010/08/26 08:29, Tobias Pape wrote:
>>
>> Am 2010-08-26 um 07:26 schrieb Hannes Hirzel:
>>
>>> On 8/26/10, Casey Ransberger<[hidden email]> wrote:
>>> ....
>>>
>>> CURRENT ACTION FOCUS
>>>>
>>>> That said, I think the web facing docs are a lower priority than gettin some
>>>> good documentation written.
>>>>
>>> I agree with the priority setting. We need to produce more
>>> documentation _within_ the image.
>>>
>>> And as the tool to stay organised we have chosen Mantis.
>>>
>>> Generating a web version of it (something like Javadoc) - I am pretty
>>> sure we will find somebody to do it. Similar things have been done in
>>> the past.
>>
>>
>> Reading that, can we interface http://soek.goodies.st/ somehow?
>
> By the way, Soek's broken at the moment:
>
> <html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
> <head>
> <title>Error</title>
> </head>
> <body onkeydown="onKeyDown(event)" onload="onLoad()">
> <h3>Transport<http> failed - Wrong response status line: PROPFIND /Soek/Launcher/ HTTP/1.1</h3>
> </body>
> </html>

Happened to me, too; interestingly, reloading helped.

So Long,
-tobias

pascal.vollmer

Re: Documentation Team

In reply to this post by Hannes Hirzel

Hannes Hirzel <hannes.hirzel <at> gmail.com> writes:

> Generating a web version of it (something like Javadoc) - I am pretty
> sure we will find somebody to do it. Similar things have been done in
> the past.

There was something like Javadoc called "Dandelion", right?
(http://www.mars.dti.ne.jp/~umejava/smalltalk/stClasses/dandelion/index.html)

Hannes Hirzel

Re: Documentation Team

On 8/26/10, Pascal Vollmer <[hidden email]> wrote:

> Hannes Hirzel <hannes.hirzel <at> gmail.com> writes:
>
>
>> Generating a web version of it (something like Javadoc) - I am pretty
>> sure we will find somebody to do it. Similar things have been done in
>> the past.
>
> There was something like Javadoc called "Dandelion", right?
> (http://www.mars.dti.ne.jp/~umejava/smalltalk/stClasses/dandelion/index.html)
>

Yes, Pascal. Dandelion is the JavaDoc like thing.

Tobias,

in the meantime I looked http://soek.goodies.st/
(I actually first thought it is like JavaDoc so I did not navigate through it)

I now think it would be good to have Squeak4.1trunk listed there.
Would it be possible for you to follow this up?

--Hannes

Tobias Pape

Re: Documentation Team

Am 2010-08-26 um 16:11 schrieb Hannes Hirzel:

> On 8/26/10, Pascal Vollmer <[hidden email]> wrote:
>> Hannes Hirzel <hannes.hirzel <at> gmail.com> writes:
>>
>>
>>> Generating a web version of it (something like Javadoc) - I am pretty
>>> sure we will find somebody to do it. Similar things have been done in
>>> the past.
>>
>> There was something like Javadoc called "Dandelion", right?
>> (http://www.mars.dti.ne.jp/~umejava/smalltalk/stClasses/dandelion/index.html)
>>
>
> Yes, Pascal. Dandelion is the JavaDoc like thing.
>
> Tobias,
>
> in the meantime I looked http://soek.goodies.st/
> (I actually first thought it is like JavaDoc so I did not navigate through it)
>
> I now think it would be good to have Squeak4.1trunk listed there.
> Would it be possible for you to follow this up?

I have no idea whom to contact or what to do to achieve this.
I just found it and found it useful. Seems to be by some VA folks
and focus on cross-Smalltalk (how odd this sound) libraries.
Does anybody know http://philemonworks.wordpress.com/ ?

So Long,
-Tobias