[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

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: [hidden email]
[mailto:[hidden email]]On Behalf Of
Matthew Fulmer
Sent: Donnerstag, 21. September 2006 11:07
To: [hidden email]
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

Matthew Fulmer a écrit :
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 <[hidden email]> wrote:

--
Software Architect
http://www.objectsroot.com/
Software is nothing

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:

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:

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.

--
brad fuller
sonaural: www.sonaural.com
personal: www.bradfuller.com
          www.oreillynet.com/pub/au/2184

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.

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

"Bakki Kudva" <[hidden email]> writes:
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

Matthew Fulmer wrote: 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

--
Craig Latta
http://netjam.org/resume

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

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:

On Thu, Sep 21, 2006 at 12:43:37PM -0400, Bakki Kudva wrote:
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

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

Cool effort. Please do it!

On 21 sept. 06, at 11:06, Matthew Fulmer wrote:

This is a reminder that the Georgia Tech Swiki Support is going away, or has this changed recently? See the following email from Mark Guzdial, dated jan 25, 2006.
I see that the SqueakSwiki link at <http://www.squeak.org> still points to <http://minnow.cc.gatech.edu/Squeak>. Has the phasing out been planned for? What happens in case of disasterous loss?
   Ken

At 9:09 AM -0500 1/25/06, Mark Guzdial wrote:
---------------------------

Nothing from what I know and it would be good to migrate it on the  
squeakfoundation machines.

Stef

On 21 sept. 06, at 22:13, Ken G. Brown wrote:

Does anybody have any info on this ?
Karl

Ken G. Brown skrev:

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.