Smalltalk › Squeak › Squeak - Dev

[ANN] Squeak Documentation Project

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

44 messages Options

123

J J-6

Re: [ANN] Squeak Documentation Project

Very good ideas. Any other successes we can steal^H^H^H^H^Hborrow ideas
from?

>From: "Bakki Kudva" <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: "The general-purpose Squeak developers
>list"<[hidden email]>
>Subject: Re: [ANN] Squeak Documentation Project
>Date: Thu, 21 Sep 2006 10:29:33 -0400
>
>Hi Mathew,
>
>This is something the noobs need badly. How about creating a community
>documentation wiki like the RailsWiki
>http://wiki.rubyonrails.org/rails
>except it should be better organized by a team leader.
>My thoughts on this...
>
>I think it should have two broad sections.
>1. Manuals
>Howtos, tutorials and long winded explanations
>2. Language reference
>The links on ref.home should map to the classes as they are displayed
>in the system browser. Categories -> Classes -> Methods. (no need for
>method categories I think) Then for each method there should be a
>brief explanation followed by example usage.
>
>The skeleton can be setup by the team and the community can start
>filling things in. Team would also do some editing of content...filter
>out spam etc.(or require login - with email verification. RailsWiki
>had some bad spam problems).
>
>I'll be happy to participate and can even host it on my server.
>my 2 cents worth.
>
>bakki
>
>On 9/21/06, Matthew Fulmer <[hidden email]> wrote:
>>After some discussion with bmp on #squeak, I have decided to
>>start writing a tutorial on squeak. bmp told me that the best
>>way to proceed with this task is to take all the documentation
>>available on the swiki [1] and massively refactor it into book
>>form.
>>
>>I am a squeak noob, and I cannot do this alone. I have created
>>an outline of my proposal [2] on the swiki. If you have a better
>>idea, please say so. I really want to get involved with this
>>amazing project. This will be a great way for us noobs to
>>contribute and learn about squeak.
>>
>>[1] http://minnow.cc.gatech.edu/squeak
>>[1] http://minnow.cc.gatech.edu/squeak/5870
>>
>>--
>>Matthew Fulmer
>>
>>
>

J J-6

Re: [ANN] Squeak Documentation Project

In reply to this post by Tapple Gao

To do the automated stuff, isn't the documentation going to have to be
inside the image?

We also need to seperate future things from "first cut" things. The biggest
enemy to any
project is "scope creep" (i.e. keep wanting to get more done before a
release).

It will be really nice to have documents auto update, but is not a
requirement for the first cut. What is a requirement is making sure all new
users to squeak quickly can find documentation without
getting overloaded with hundreds of documents.

>From: Matthew Fulmer <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: [hidden email]
>Subject: Re: [ANN] Squeak Documentation Project
>Date: Thu, 21 Sep 2006 10:09:48 -0700
>
>On Thu, Sep 21, 2006 at 12:43:37PM -0400, Bakki Kudva wrote:
> > Hi Lex, Mathew,
> >
> > I have seen the swiki and perhaps my choice of words "creating a wiki"
> > was wrong and misleading. I do think that the language ref
> > particularly needs 'the love' Brad is talking about. I have found that
> > the php reference was the best I've ever used.
> > http://www.php.net/manual/en/
> > The reason is that there is a quick way to find the info on the
> > particular php function, where you find its description, example code
> > and usage notes from users. We could do something similar. However I
> > feel that most smalltalkers first get familiar (newbies like me) with
> > the system browser while exploring code and so if the index page of
> > the ref manual is organized the same way then one could quickly find a
> > class>>method page and the information there could follow the same
> > format for all methods:
> >
> > Description:.......................
> > Example code: ...................
> > User notes: ......................
> >
> > This could use some nice css to box each section in a squeak like
> > frame with different colors etc.
> >
> > WHy not emulate and improve upon something that works really well?
>
>This is exactly what I want to build, but for Squeak/Smalltalk
>
> > Seaside halos already exposes the object heirarchy. Perhaps this could
> > be extended to be the documentation engine with the code edit
> > capability ofcourse turned off?
>
>The more automatic this process can be, the better. I may look
>into it later, but for now, I want to compile a comprehensive
>Squeak documentation index so that we have a place to start. So
>far, the Swiki seems like the best place to do this, however, I
>am not familiar with all the technology that squeak offers in
>this area. I have zero experience with Seaside. If Seaside is
>better suited to the documentation project, we should definitely
>use it.
>
> > On 21 Sep 2006 17:58:23 +0200, Lex Spoon <[hidden email]> wrote:
> > >Have you guys looked at the Documentation wiki area we already have?
> > >It is linked from the front page of the wiki.
> > >
> > > http://minnow.cc.gatech.edu/squeak/2983
>
>Yes, I have. I plan to use it too. There are frameworks already
>in place for doing what I want to do, we just need to make use
>of them.
>
>--
>Matthew Fulmer
>

J J-6

Re: [ANN] Squeak Documentation Project

In reply to this post by Tapple Gao

Sounds good. By the way, this stuff also needs to be pointed to from
squeak.org. I think that is the place most new squeak users are going to
check first so the new doc should be easily found from there.

>From: Matthew Fulmer <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: [hidden email]
>Subject: Re: [ANN] Squeak Documentation Project
>Date: Thu, 21 Sep 2006 10:58:38 -0700
>
>On Thu, Sep 21, 2006 at 09:44:27AM -0700, Eric Winger wrote:
> > This is one of the problems with Smalltalk in general, as I see it.
> > There's a ton of documentation available on Smalltalk, not just Squeak.
> > But when you're starting out, you don't want all that. You need a
> > straight forward, single, starting point to get going.
>
>That is what I hope to create.
>
> > The stic group, through the smalltalk-central.com site is trying to
> > centralize a lot of Smalltalk information into one place for people
> > curious about Smalltalk.
>
>Should the squeak documentation project focus it's efforts at
>that site, rather than the Swiki?
>
> > Right now, in the tutorials sections on smalltalk-central.com, there
> > are inumerable tutorials on squeak and aspects of squeak. Where does a
> > newbie start?
> >
> > It would be nice to get a squeak tutorial that is concise,
> > well-written, well-formatted and designed for the beginner. If nothing
> > else, so he doesn't have to wade through 50 tutorials to get started.
>
>To begin, I want to create a comprehensive index of all existing
>Squeak-applicable documentation. That way, we know what we can
>plagiarize and what we will need to write from scratch. Of
>course, I do not want to use someones work without permission,
>but I do not know of a categorical index to all the available
>documentation. I have created a template index, and I will begin
>creating content there soon:
>
>http://minnow.cc.gatech.edu/squeak/5871
>
>Once that progresses, we can obtain permission to use those
>documents that are available and re-create them in the form of a
>comprehensive Squeak Reference Manual and a Tutorial. That is my
>road map.
>
>--
>Matthew Fulmer
>

Tapple Gao

Contributing to the Documentation Team

In reply to this post by Tapple Gao

I have seen several people wishing to contribute their efforts
to this project. Thank you all for volunteering. This will be an
open project, so anyone can contribute. However, those on the
team will decide what the overall goals will be.

How can you contribute?
1. Read the goals and plans of the tutorial project:
http://minnow.cc.gatech.edu/squeak/5870
2. Post ideas and suggestions to the mailing list.
3. If you have a good idea, you can get Swiki edit permissions:
3.1. Join #squeak, and ask me for wiki edit permissions.
3.2. Start adding to the Tutorial:
http://minnow.cc.gatech.edu/squeak/5869

I put instructions on contributing on the documentation team
page:
http://minnow.cc.gatech.edu/squeak/808

--
Matthew Fulmer

Tapple Gao

Re: [ANN] Squeak Documentation Project

In reply to this post by J J-6

On Sat, Sep 23, 2006 at 01:39:03PM +0000, J J wrote:

> To do the automated stuff, isn't the documentation going to have to be
> inside the image?
>
> We also need to seperate future things from "first cut" things. The
> biggest enemy to any
> project is "scope creep" (i.e. keep wanting to get more done before a
> release).
>
> It will be really nice to have documents auto update, but is not a
> requirement for the first cut. What is a requirement is making sure all
> new users to squeak quickly can find documentation without
> getting overloaded with hundreds of documents.

These are all really nice ideas. However, we need to stay
focused if we want to get the documentation team off the ground.
Please record your ideas at the future projects page:
http://minnow.cc.gatech.edu/squeak/809

If you are interested in contributing, see
http://minnow.cc.gatech.edu/squeak/808

> >From: Matthew Fulmer <[hidden email]>
> >Reply-To: The general-purpose Squeak developers
> >list<[hidden email]>
> >To: [hidden email]
> >Subject: Re: [ANN] Squeak Documentation Project
> >Date: Thu, 21 Sep 2006 10:09:48 -0700
> >
> >On Thu, Sep 21, 2006 at 12:43:37PM -0400, Bakki Kudva wrote:
> >> Hi Lex, Mathew,
> >>
> >> I have seen the swiki and perhaps my choice of words "creating a wiki"
> >> was wrong and misleading. I do think that the language ref
> >> particularly needs 'the love' Brad is talking about. I have found that
> >> the php reference was the best I've ever used.
> >> http://www.php.net/manual/en/
> >> The reason is that there is a quick way to find the info on the
> >> particular php function, where you find its description, example code
> >> and usage notes from users. We could do something similar. However I
> >> feel that most smalltalkers first get familiar (newbies like me) with
> >> the system browser while exploring code and so if the index page of
> >> the ref manual is organized the same way then one could quickly find a
> >> class>>method page and the information there could follow the same
> >> format for all methods:
> >>
> >> Description:.......................
> >> Example code: ...................
> >> User notes: ......................
> >>
> >> This could use some nice css to box each section in a squeak like
> >> frame with different colors etc.
> >>
> >> WHy not emulate and improve upon something that works really well?
> >
> >This is exactly what I want to build, but for Squeak/Smalltalk
> >
> >> Seaside halos already exposes the object heirarchy. Perhaps this could
> >> be extended to be the documentation engine with the code edit
> >> capability ofcourse turned off?
> >
> >The more automatic this process can be, the better. I may look
> >into it later, but for now, I want to compile a comprehensive
> >Squeak documentation index so that we have a place to start. So
> >far, the Swiki seems like the best place to do this, however, I
> >am not familiar with all the technology that squeak offers in
> >this area. I have zero experience with Seaside. If Seaside is
> >better suited to the documentation project, we should definitely
> >use it.
> >
> >> On 21 Sep 2006 17:58:23 +0200, Lex Spoon <[hidden email]> wrote:
> >> >Have you guys looked at the Documentation wiki area we already have?
> >> >It is linked from the front page of the wiki.
> >> >
> >> > http://minnow.cc.gatech.edu/squeak/2983
> >
> >Yes, I have. I plan to use it too. There are frameworks already
> >in place for doing what I want to do, we just need to make use
> >of them.
> >
> >--
> >Matthew Fulmer
> >
>
>
>
>

--
Matthew Fulmer

stephane ducasse-2

Re: Contributing to the Documentation Team

In reply to this post by Tapple Gao

matthew you can use my videos if you want to illustrate some of your
tutorial

http://www.listic.univ-savoie.fr/~ducasse/Ressources....

On 23 sept. 06, at 19:31, Matthew Fulmer wrote:

> I have seen several people wishing to contribute their efforts
> to this project. Thank you all for volunteering. This will be an
> open project, so anyone can contribute. However, those on the
> team will decide what the overall goals will be.
>
> How can you contribute?
> 1. Read the goals and plans of the tutorial project:
> http://minnow.cc.gatech.edu/squeak/5870
> 2. Post ideas and suggestions to the mailing list.
> 3. If you have a good idea, you can get Swiki edit permissions:
> 3.1. Join #squeak, and ask me for wiki edit permissions.
> 3.2. Start adding to the Tutorial:
> http://minnow.cc.gatech.edu/squeak/5869
>
> I put instructions on contributing on the documentation team
> page:
> http://minnow.cc.gatech.edu/squeak/808
>
> --
> Matthew Fulmer
>

Tapple Gao

Re: [ANN] Squeak Documentation Project

In reply to this post by J J-6

On Sat, Sep 23, 2006 at 01:13:06PM +0000, J J wrote:
> Excellent. This really needs to be done desperately. I would be
> interested in any help I can offer. Is there a list somewhere of who all
> will be involved? We need to get everyone together and lay out what gets
> documented first cut, and probably try to make a cut at the chapters so the
> documentation can be done concurrently.

You can sign up at the documentation team page:
http://minnow.cc.gatech.edu/squeak/808

The first cut of an outline has also been made:
http://minnow.cc.gatech.edu/squeak/5869

Go ahead and add your ideas. I will put together a voting form
to determine exactly what should and should not be in the
document.

--
Matthew Fulmer

Tapple Gao

Re: Contributing to the Documentation Team

In reply to this post by stephane ducasse-2

On Sat, Sep 23, 2006 at 08:25:13PM +0200, stephane ducasse wrote:
> http://www.listic.univ-savoie.fr/~ducasse/Ressources....

This url leads to a page error

--
Matthew Fulmer

J J-6

Re: Contributing to the Documentation Team

In reply to this post by stephane ducasse-2

Can someone convert these also to MPEG or something? I hate downloading 20
different programs just to watch the different movies. And the quicktime
stuff is the worst.

Thanks in advance.

>From: stephane ducasse <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: The general-purpose Squeak developers
>list<[hidden email]>
>Subject: Re: Contributing to the Documentation Team
>Date: Sat, 23 Sep 2006 20:25:13 +0200
>
>matthew you can use my videos if you want to illustrate some of your
>tutorial
>
>http://www.listic.univ-savoie.fr/~ducasse/Ressources....
>
>
>On 23 sept. 06, at 19:31, Matthew Fulmer wrote:
>
>>I have seen several people wishing to contribute their efforts
>>to this project. Thank you all for volunteering. This will be an
>>open project, so anyone can contribute. However, those on the
>>team will decide what the overall goals will be.
>>
>>How can you contribute?
>>1. Read the goals and plans of the tutorial project:
>> http://minnow.cc.gatech.edu/squeak/5870
>>2. Post ideas and suggestions to the mailing list.
>>3. If you have a good idea, you can get Swiki edit permissions:
>> 3.1. Join #squeak, and ask me for wiki edit permissions.
>> 3.2. Start adding to the Tutorial:
>> http://minnow.cc.gatech.edu/squeak/5869
>>
>>I put instructions on contributing on the documentation team
>>page:
>>http://minnow.cc.gatech.edu/squeak/808
>>
>>--
>>Matthew Fulmer
>>
>
>

J J-6

Re: Contributing to the Documentation Team

In reply to this post by Tapple Gao

You can just go to squeak.org -> documentation. It is the first or second
link on that page. It's tons of little movies, very nice. (but .mov format)

>From: Matthew Fulmer <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: [hidden email]
>Subject: Re: Contributing to the Documentation Team
>Date: Sat, 23 Sep 2006 13:02:58 -0700
>
>On Sat, Sep 23, 2006 at 08:25:13PM +0200, stephane ducasse wrote:
> > http://www.listic.univ-savoie.fr/~ducasse/Ressources....
>
>This url leads to a page error
>
>--
>Matthew Fulmer
>

Mathieu SUEN

Re: Contributing to the Documentation Team

In reply to this post by Tapple Gao

Matthew Fulmer a écrit :
> On Sat, Sep 23, 2006 at 08:25:13PM +0200, stephane ducasse wrote:
>> http://www.listic.univ-savoie.fr/~ducasse/Ressources....
>
> This url leads to a page error
>
try this
http://www.iam.unibe.ch/~ducasse/Videos/

Edgar J. De Cleene

Re: Contributing to the Documentation Team

In reply to this post by J J-6

J J puso en su mail :

> Can someone convert these also to MPEG or something? I hate downloading 20
> different programs just to watch the different movies. And the quicktime
> stuff is the worst.
>
> Thanks in advance.
I do few days after Stephane release.
Are in
ftp://[hidden email]/
password: elpelotero (on approximate 09:00 to 20:00 GMT, dig and take what
you like, at your own risk)

Also the Helpzip.zip of Maartens.

I feels some guilty as I can't have time to this now...(resurrecting old
stuff, trying to follow Pavel, trying to have a DeLuxeSqueakLight, etc)

Edgar

__________________________________________________
Preguntá. Respondé. Descubrí.
Todo lo que querías saber, y lo que ni imaginabas,
está en Yahoo! Respuestas (Beta).
¡Probalo ya!
http://www.yahoo.com.ar/respuestas

J J-6

Re: Request for links (was: [ANN] Squeak Documentation Project)

In reply to this post by Tapple Gao

Hello group,

One of the deliverables from the Documentation project is a comprehensive
index of available documentation. So if everyone who knows of some
not-so-well-known documentation please send it. If you don't want to put it
on the list you can send it to Mathew and myself.

I have some stuff I have found myself and will include that, but everytime I
ask a question one of you points me at some link I have never seen before
prior. So if you could send us those, and don't worry about duplicating
what someone else sent, we will compile an index out of what you send.

Thanks,
JJ

Chema Ortega

Re: Contributing to the Documentation Team

In reply to this post by Tapple Gao

Well, as I talk with Mattew, translation could be a good point in the
tutorial/documentation proyect. I'm not fully sure if another team need
to be started, but links at the end of the page showing the translated
page to other languages will help people to read that info in their own
language.

I can translate texts to spanish as they come, it's a never ending work,
but I'll try my best.

Any other one could help in this localization work?

El sáb, 23-09-2006 a las 10:31 -0700, Matthew Fulmer escribió:

signature.asc (198 bytes) Download Attachment

Ralph Johnson

Re: Request for links (was: [ANN] Squeak Documentation Project)

In reply to this post by J J-6

> One of the deliverables from the Documentation project is a comprehensive
> index of available documentation. So if everyone who knows of some
> not-so-well-known documentation please send it. If you don't want to put it
> on the list you can send it to Mathew and myself.

What do you mean by "documentation"? One reason that documentation is
a problem is that so much has been written, but some of it is
advanced, some of it is for Smalltalk in general, which might or might
not be applicable, some of it is old and no longer 100% correct, some
of it is written in mailing lists rather than as formal documents. Do
you want lecture notes, documentation for particular packages, videos?

My guess is that the best way to find what is relevant is to do what
you are doing, i.e. to ask questions and to see which documents you
are given for answers.

-Ralph

J J-6

Re: Request for links (was: [ANN] Squeak Documentation Project)

At this point, I would say everything you know about. I mean, the stuff on
squeak.org and whysmalltalk.com I have tracked down, but I am sure you have
spots you go to that I am not aware of.

If the information is too much we can take a time out and go through and
classify it. But we will need all levels of documentation before we are
finished.

>From: "Ralph Johnson" <[hidden email]>
>Reply-To: The general-purpose Squeak developers
>list<[hidden email]>
>To: "The general-purpose Squeak developers
>list"<[hidden email]>
>Subject: Re: Request for links (was: [ANN] Squeak Documentation Project)
>Date: Sun, 24 Sep 2006 07:46:10 -0500
>
>>One of the deliverables from the Documentation project is a comprehensive
>>index of available documentation. So if everyone who knows of some
>>not-so-well-known documentation please send it. If you don't want to put
>>it
>>on the list you can send it to Mathew and myself.
>
>What do you mean by "documentation"? One reason that documentation is
>a problem is that so much has been written, but some of it is
>advanced, some of it is for Smalltalk in general, which might or might
>not be applicable, some of it is old and no longer 100% correct, some
>of it is written in mailing lists rather than as formal documents. Do
>you want lecture notes, documentation for particular packages, videos?
>
>My guess is that the best way to find what is relevant is to do what
>you are doing, i.e. to ask questions and to see which documents you
>are given for answers.
>
>-Ralph
>

Lex Spoon

Re: [ANN] Squeak Documentation Project

In reply to this post by Eric Winger

Eric Winger <[hidden email]> writes:
> This is one of the problems with Smalltalk in general, as I see
> it. There's a ton of documentation available on Smalltalk, not just
> Squeak. But when you're starting out, you don't want all that. You
> need a straight forward, single, starting point to get going.

That's a strange comment. Have you looked at the "getting started"
area on the Squeak swiki? It includes a number of tutorials, plus
references to a number of books. It includes much Squeak-specific
material.

http://minnow.cc.gatech.edu/squeak/377

It includes tutorials, free books you can download, and pointers to
books in print.

-Lex

Lex Spoon

Re: [ANN] Squeak Documentation Project

In reply to this post by Bakki Kudva

"Bakki Kudva" <[hidden email]> writes:
> I have seen the swiki and perhaps my choice of words "creating a wiki"
> was wrong and misleading. I do think that the language ref
> particularly needs 'the love' Brad is talking about. I have found that
> the php reference was the best I've ever used.
> http://www.php.net/manual/en/
> The reason is that there is a quick way to find the info on the
> particular php function, where you find its description, example code
> and usage notes from users.

It's even faster in Squeak -- you get all of this information directly
from your image, with no network delay. You can even run the example
code directly, without having to cut and paste.

Thus, forgive me if I think people may be misunderstanding what is
already available. Writing up a bunch of HTML documenting individual
methods and classes does not make sense for Squeak.

Instead, it makes sense to concentrate on two other areas:

1. Improving Squeak's own self-documentation. Many methods
and classes are not documented.

2. Write articles with broader scope. If you want to know what
the methods of Canvas are, then look in your image. If you want to
know how Canvas fits into the Morphic architecture, then you need
to read a broader article about Morphic (e.g., the chapter in the
"nu-blue" book).

-Lex

Bakki Kudva

Re: Request for links (was: [ANN] Squeak Documentation Project)

In reply to this post by J J-6

I agree absolutely.

Collate -> Refactor -> AddNewStuff.

bakki

On 9/24/06, J J <[hidden email]> wrote:
> At this point, I would say everything you know about. I mean, the stuff on
> squeak.org and whysmalltalk.com I have tracked down, but I am sure you have
> spots you go to that I am not aware of.
>
> If the information is too much we can take a time out and go through and
> classify it. But we will need all levels of documentation before we are
> finished.
>

Bakki Kudva

Re: [ANN] Squeak Documentation Project

In reply to this post by Lex Spoon

On 25 Sep 2006 14:18:04 +0200, Lex Spoon <[hidden email]> wrote:

> It's even faster in Squeak -- you get all of this information directly
> from your image, with no network delay. You can even run the example
> code directly, without having to cut and paste.

And Seaside exposes this entire heirarchy to the web browser via the
WABrowser, WAHalo and other classes in the Seaside-Components-Tools.
OFcourse the main objective there is to inspect, edit the application
code. However I thought (still trying to wrap my newbie mind around
this) that there must be a way that these classes can be extended such
that:

1. Code editing and halo specific is turned off.
2. Sections added to the renderContentOn: methods for COMMUNITY
contributed method descriptions and SAMPLE CODE with pretty css.
3. Contributed code NOT saved in the Image but saved in a seperate db
using magma or some other mechanism indexed by Category -> Class ->
Method.

This would make it a Seaside driven community documentation engine for
Squeak. This way one could browse the object heirarchy on the web and
get community contributed docs in a squeak like environment.

-bakki

> Thus, forgive me if I think people may be misunderstanding what is
> already available. Writing up a bunch of HTML documenting individual
> methods and classes does not make sense for Squeak.
>
> Instead, it makes sense to concentrate on two other areas:
>
> 1. Improving Squeak's own self-documentation. Many methods
> and classes are not documented.
>
> 2. Write articles with broader scope. If you want to know what
> the methods of Canvas are, then look in your image. If you want to
> know how Canvas fits into the Morphic architecture, then you need
> to read a broader article about Morphic (e.g., the chapter in the
> "nu-blue" book).
>
>
>
> -Lex
>
>
>

123