[ANN] Squeak Documentation Project

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:
>
>   1. Improving Squeak's own self-documentation.  Many methods
>   and classes are not documented.

Exactly; in-code documentation needs lots of work

>
>   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).

...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; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: CPM: Change Programmer's Mind

On Sep 25, 2006, at 5:09 AM, Lex Spoon wrote:

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

tim Rowledge <[hidden email]> writes:

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

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.

--
Matthew Fulmer