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
Just noticed the mp3 (Masayah - One Dance.mp3) on http://minnow.cc.gatech.edu/squeak. I guess someone missed it or is it the new squeak theme tune?
-----Original Message----- From: squeak-dev-bounces@lists.squeakfoundation.org [mailto:squeak-dev-bounces@lists.squeakfoundation.org]On Behalf Of Matthew Fulmer Sent: Donnerstag, 21. September 2006 11:07 To: squeak-dev@lists.squeakfoundation.org Subject: [ANN] Squeak Documentation Project
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
-- No virus found in this incoming message. Checked by AVG Free Edition. Version: 7.1.405 / Virus Database: 268.12.6/453 - Release Date: 20.09.2006
James Hayes wrote:
Just noticed the mp3 (Masayah - One Dance.mp3) on http://minnow.cc.gatech.edu/squeak. I guess someone missed it or is it the new squeak theme tune?
that's strange! I'm listening to it, and I don't hear the connection to Squeak.
Matthew Fulmer a écrit :
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
You can look at our french Wiki : http://community.ofset.org/wiki/Squeak We are using MediaWiki. This is not as big (roughly more than 150 pages) as minnow, but we tried to categorize carefully each of page.
-- oooo Dr. Serge Stinckwich OOOOOOOO Université de Caen>CNRS UMR 6072>GREYC>MAD OOESUGOO http://purl.org/net/SergeStinckwich oooooo Smalltalkers do: [:it | All with: Class, (And love: it)] \ / ##
Take a look also at my tutorial: http://www.objectsroot.com/squeak/squeak_tutorial.html Bye bye
On 9/21/06, Matthew Fulmer tapplek@gmail.com 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
Matthew,
I am writing a (brief) overview of:
How to manage code, projects, and releases with Monticello, SqueakSource and SqueakMap.
This is "for myself" so not sure how useful it will be. I want to interrupt that work now for until next week, but please remind me in a week or two, when I should be done, if you are interested to include that, I will send you the link.
Milan
On 2006 September 21 05:06, Matthew Fulmer 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
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 tapplek@gmail.com 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
On Thu, Sep 21, 2006 at 10:29:33AM -0400, Bakki Kudva wrote:
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.
I agree with you about the need for a community documentation wiki. However, we already have such a wiki. I think that we should stick with the existing minnow Swiki, rather than make a new one from scratch. The Swiki has a *lot* of information already; it just needs love to put it into a nice hierarchy. I know that Swiki is not the best wiki software at the moment, but it is nearly always better to work with what you have than to start over. And, if Squeak is as good as we say it is, Swiki should be the premiere wiki software in a couple of years.
My thoughts on this...
I think it should have two broad sections.
- 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).
The minnow Swiki is a members-only wiki, meaning that you need to ask on IRC for the user name and password. That may need to change, but it is not in my power.
I'll be happy to participate and can even host it on my server. my 2 cents worth.
Thanks. I will need all the help I can get. I put up a voting page to see what the community thinks: should we stick with the minnow Swiki, or should we start over:
http://minnow.cc.gatech.edu/squeak/5870 (at the bottom)
Matthew Fulmer wrote:
On Thu, Sep 21, 2006 at 10:29:33AM -0400, Bakki Kudva wrote:
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.
I agree with you about the need for a community documentation wiki. However, we already have such a wiki. I think that we should stick with the existing minnow Swiki, rather than make a new one from scratch. The Swiki has a *lot* of information already; it just needs love to put it into a nice hierarchy. I know that Swiki is not the best wiki software at the moment, but it is nearly always better to work with what you have than to start over. And, if Squeak is as good as we say it is, Swiki should be the premiere wiki software in a couple of years
It does need a lot of love. It needs a lot of pruning and updating. One option would be to select the appropriate content on minnow, pruned/edit/improve it and place it in a new wiki (Pier Wiki?) in the appropriate place. Maybe this "appropriate" place is an already made hierarchy or however it is decided to organize the new wiki. (personally, I'd like to see a dynamic mind map using connectors package with seaside. Something like this: http://www.thebrain.com/ - you'll need java plugin enabled to view) The benefit to the editor(s) is that he gets to read and do a little learning while editing into the new wiki.
Is there a documentation team?
Hi Brad--
Is there a documentation team?
It looks like there isn't, officially[1]. I guess that's about to change, cool!
-C
[1] http://www.squeak.org/Community/Teams
"Bakki Kudva" bakki.kudva@gmail.com writes:
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.
- Manuals
Howtos, tutorials and long winded explanations 2. Language reference
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
I'll append its table of contents. In my view, we already have an excellent documentation framework. The place people can help is to actually write these nice articles.
-Lex
For this page to be meaningful requires the effort of the whole Squeak comunity. To contribute see How to help us document Squeak.
Thanks, the management.
Introduction
* About Squeak o The History of Squeak + The Early History of Smalltalk by Alan C. Kay + Travels with Smalltalk by Dave Thomas traces the larger history of Smalltalk up to the 90s + Quotes and anecdotes + Squeak's Place in the Universe o Features o Supported platforms o License, see Squeak-L * Squeak and Smalltalk Basics o Smalltalk: A White Paper Overview by Harry Porter o Smalltalk overview o ANSI Smalltalk: the standard. o Learn Smalltalk o Squeak's programming language: Smalltalk and Squeak's dialect of it. o The Squeak and Smalltalk Glossary
Getting started
* Squeak FAQ: Frequently Asked Questions about Squeak * Reporting Bugs and Fixes * Squeak Mailing List * Obtaining Squeak o Downloading Squeak * Installing Squeak o How do I install Squeak for Windows? o How do I install Squeak for Mac? o Download for Unix + Squeak for Debian Users o BSD * Learning Squeak o Introductions to Squeak o Self Study course for learning Squeak. o The Newbie page o Squeak Cookbook %Gâ%@ HowTo o Squeak for Non-Native Speakers (pdf), by Noel Rappin of EchoBridge. o Squeak, the Smalltalk of the 21st. Century, by Germán Arduino.
Using Squeak
* Interacting with Squeak o Squeak User Interface: working with Squeak's interface o Morphic: Squeak's newer graphics framework o MVC: The older graphics framework + Forms, Views, and Windows + The FormEditor o Fonts in Squeak * Configuring and Tuning o User Preferences * Installing Applications o SqueakMap: Add Packages to your Image o SqueakMap Usage HOWTO: How to work with SqueakMap and the Package o Monticello concurrent versioning system for Squeak code. * Printing o Postscript support * Storage o Introduction to ImageSegments #3 o Files and Directories * Localization o Squeak Localization o Multilingual Support * Multimedia o Sound and music o Video o Squeak-specific media o 3D o Presentation authoring o Presentaciones en Squeak, by Germán Arduino. This article is in Spanish, translators are welcomed! * Networking o Internet integration o Mail + Celeste o World Wide Web + Swiki + Comanche + SmallWiki o Scamper * Miscellaneous o Squeak Threading Model o FFI
Programming with Squeak
* Introduction o Basic Squeak Development Tools: %Gâ%@ Browsers, Workspaces, Inspectors, etc. o SUnit S-Unit Testing Framework o Hello World programs %Gâ%@ Ways of how to make a simple 'Hello World' Application o Dependencies o Monticello concurrent versioning system for Squeak code. * Programming with the Squeak User Interface o BitBlt o see also Using Squeak o Block Closures %Gâ%@ Blocks in Squeak o Processes o Exception Handling * Storage o Introduction to ImageSegments #3 o Files * Networking
Inside Squeak
* System Documentation * The Squeak Image * The Virtual Machine o VM Command Line Options o The Interpreter o Simulating the Interpreter: running the Squeak VM from within Squeak. o The Object Memory (the heap) o The Squeak Garbage Collector o Porting Squeak
Bugs and Fixes
* Reporting Bugs and Fixes * Bug Fixes Archive * Known Bugs * ClassDescription
Appendices
* Bibliography o Squeak books in print %Gâ%@ Books about Squeak o Smalltalk books %Gâ%@ Books about Smalltalk in general o Videos and Presentations * Resources on the Internet o http://www.squeak.org/ %Gâ%@ The official Squeak Homepage o http://www.smalltalk.org/ %Gâ%@ The official Smalltalk Homepage o http://www.whysmalltalk.com/ %Gâ%@ huge collection of Tutorials, HowTos and much more about Smalltalk * Also see: o the class comments inside your Squeak image, o the available projects on various Super Swikis, and o the package descriptions in SqueakMap
Miscellaneous - orphaned
* Older Front Page Links o Bibliography Online papers on Squeak, Smalltalk, and object-oriented programming - very extensive! o Modules - documentation about the modules/packages/repository system that was added to 3.3. (now obsolete!) o Squeak on Handhelds: running Squeak on machines like the iPaq. o Uncategorized Essays: miscellanous documentation that doesn't fit elsewhere. o Essays Wanted %Gâ%@ essays that it would be wonderful to have around, but which aren't. o Cash for Documentation %Gâ%@ help support the Squeak community by bidding for needed documentation * Cleanup - to be moved? o Cleanup/Enhancement Projects o Documentation o Morphic Cleanup Project (MCP) o EventRecorderMorph o Squeak Documentation Project (SDP) o Factoring Squeak 3.4+ into Packages o Finding Stewards for Packages
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?
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?
-bakki
On 21 Sep 2006 17:58:23 +0200, Lex Spoon lex@cc.gatech.edu wrote:
Have you guys looked at the Documentation wiki area we already have? It is linked from the front page of the wiki.
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 lex@cc.gatech.edu wrote:
Have you guys looked at the Documentation wiki area we already have? It is linked from the front page of the wiki.
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.
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 tapplek@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: squeak-dev@lists.squeakfoundation.org 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 lex@cc.gatech.edu wrote:
Have you guys looked at the Documentation wiki area we already have? It is linked from the front page of the wiki.
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
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 tapplek@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: squeak-dev@lists.squeakfoundation.org 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 lex@cc.gatech.edu wrote:
Have you guys looked at the Documentation wiki area we already have? It is linked from the front page of the wiki.
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
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
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
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" johnson@cs.uiuc.edu Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "The general-purpose Squeak developers list"squeak-dev@lists.squeakfoundation.org 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
I agree absolutely.
Collate -> Refactor -> AddNewStuff.
bakki
On 9/24/06, J J azreal1977@hotmail.com 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" bakki.kudva@gmail.com 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
On 25 Sep 2006 14:18:04 +0200, Lex Spoon lex@cc.gatech.edu 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:
- Improving Squeak's own self-documentation. Many methods
and classes are not documented.
- 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
On 25-Sep-06, at 5:18 AM, Lex Spoon wrote: [snip]
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:
- Improving Squeak's own self-documentation. Many methods
and classes are not documented.
Exactly; in-code documentation needs lots of work
- 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).
...and don't forget an article/tutorial on using the tools so that new users are able to look in the image for the improved class comments. Teaching about effective use of the tools is almost as important as providing a good basis for understanding objects and messages.
What will almost certainly happen as you write such a tutorial is that you will find assorted logical or work-flow problems with the tools, which we can then fix. Hopefully. I think of this as 'Documentation Driven Design' - if you can't write a simple and comprehensible explanation then there is a good chance your app doesn't work the way it should.
tim -- tim Rowledge; tim@rowledge.org; http://www.rowledge.org/tim Strange OpCodes: CPM: Change Programmer's Mind
tim Rowledge tim@rowledge.org writes:
On 25-Sep-06, at 5:18 AM, Lex Spoon wrote: [snip]
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:
- Improving Squeak's own self-documentation. Many methods
and classes are not documented.
Exactly; in-code documentation needs lots of work
- 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).
...and don't forget an article/tutorial on using the tools so that new users are able to look in the image for the improved class comments. Teaching about effective use of the tools is almost as important as providing a good basis for understanding objects and messages.
Absolutely. You'll be as happy as I to know that on page number *four* on the Squeak swiki -- i.e., the third page created after its creation -- you find information about how to use all of the built-in Squeak development tools plus a few optional ones.
http://minnow.cc.gatech.edu/squeak/4
-Lex
Very good ideas. Any other successes we can steal^H^H^H^H^Hborrow ideas from?
From: "Bakki Kudva" bakki.kudva@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: "The general-purpose Squeak developers list"squeak-dev@lists.squeakfoundation.org 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.
- 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 tapplek@gmail.com 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
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.
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.
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.
Eric
On Sep 21, 2006, at 2:06 AM, Matthew Fulmer 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
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.
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 tapplek@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: squeak-dev@lists.squeakfoundation.org 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
Eric Winger eric@thewingers.net 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
On Sep 25, 2006, at 5:09 AM, Lex Spoon wrote:
Eric Winger eric@thewingers.net 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/377It includes tutorials, free books you can download, and pointers to books in print.
Your link exactly illustrates my point. You didn't send me to a link with a simple tutorial using Squeak 3.9. You sent me to a page with lots of stuff, albeit very good stuff, but lots and lots of stuff, which may or may not be out of date. For a person new to smalltalk and squeak that's too much.
That's why the documentation project discussion is a good idea. Written by newbies for newbies. It would be really neat if it comes together well and the result will be a nice set of well-maintained tutorials that a beginner can start with, then grow with as they gain experience. Further, the new user would open squeak and be presented with links to these tutorials. Then, in his mind, there would be no question as to where to start. and no question that he would be using a tutorial that wasn't out of date.
After a person has their feet wet and wants to explore further, then all that other documentation is great.
my 2 cents,
Eric
Cool effort. Please do it!
On 21 sept. 06, at 11:06, Matthew Fulmer 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
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.
From: Matthew Fulmer tapplek@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: squeak-dev@lists.squeakfoundation.org Subject: [ANN] Squeak Documentation Project Date: Thu, 21 Sep 2006 02:06:59 -0700
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
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.
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 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?
- Read the goals and plans of the tutorial project: http://minnow.cc.gatech.edu/squeak/5870
- Post ideas and suggestions to the mailing list.
- 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
On Sat, Sep 23, 2006 at 08:25:13PM +0200, stephane ducasse wrote:
This url leads to a page error
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 tapplek@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: squeak-dev@lists.squeakfoundation.org 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:
This url leads to a page error
-- Matthew Fulmer
Matthew Fulmer a écrit :
On Sat, Sep 23, 2006 at 08:25:13PM +0200, stephane ducasse wrote:
This url leads to a page error
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 stephane.ducasse@gmail.com Reply-To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org To: The general-purpose Squeak developers listsqueak-dev@lists.squeakfoundation.org 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?
- Read the goals and plans of the tutorial project: http://minnow.cc.gatech.edu/squeak/5870
- Post ideas and suggestions to the mailing list.
- 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 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://elpelotero@201-212-99-13.cab.prima.net.ar/ 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
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ó:
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?
- Read the goals and plans of the tutorial project: http://minnow.cc.gatech.edu/squeak/5870
- Post ideas and suggestions to the mailing list.
- 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
First, I apologize for not keeping in touch with those of you who have volunteered to help.
Thank you everyone who has volunteered so far. We currently have three projects going on:
- Creating a Squeak Quick-start tutorial. Leader: Matthew Fulmer
- Upkeep of the Squeak Documentation index at: http://minnow.cc.gatech.edu/squeak/2983 Leader: Matthew Fulmer
- Aaron Reichow has begun planning an update of the Morphic tutorials.
If you have a particular interest, please express it so that you can find others with the same interest. Choose a project, find a team with the same interests, and start contributing! Also, list your project at: http://minnow.cc.gatech.edu/squeak/812
If you do not know where to start, or what you are interested in, I need help with the beginner's quick-start tutorial, especially chapter 3: http://minnow.cc.gatech.edu/squeak/5869
Also, please consider getting an IRC client and joining the discussion on the #squeak channel at chat.freenode.net. A lot of discussion happens there.
Thank you all for your willingness to contributing to the Squeak community! Let's make it an even better place than it is now.
squeak-dev@lists.squeakfoundation.org
-
Bakki Kudva -
Brad Fuller -
Chema Ortega -
Craig Latta -
Edgar J. De Cleene -
Eric Winger -
Giovanni Giorgi -
J J -
James Hayes -
Lex Spoon -
Mathieu -
Matthew Fulmer -
Milan Zimmermann -
Ralph Johnson -
Serge Stinckwich -
stephane ducasse -
tim Rowledge