"Noel J. Bergman" <noel at devtech.com> wrote:


> > I *knew* that such a list was on the swiki, but it took me
> > a few minutes -- it's listed under "Getting Started with
> > Squeak" instead of under "Documentation", which now that I
> > think about it, is a pretty fine line to draw.
> 
> Ought to be under both.  :-)  It IS documentation, and it IS about getting
> started.  Actually, I'd have looked in the latter first, whereas I would
> expect that experienced Squeakers bypass "getting started" sections.
> 

I worded it badly.  My point is more that, isn't *most* documentation
aimed at newbies?  Where do we draw the line?

There are two main things I see a rank newbie needing:

	1. Instructions on getting Squeak downloaded and running.
	2. Tutorials to learn how to do very basic things in the environment.

We already have a DownloadingSqueak page.  We don't have a page
specifically for introductory tutorials, though -- instead, we have big
"newbie one-stop" pages.  I think it's worth having a page just for
introductory tutorials, and then moving the other newbie material
elsewhere.

Let's look at what's on the "Learning to Squeak" page right now--I'll
argue that most of it should be elsewhere.  Afterwards, I'll suggest a
new hierarchy for documentation pages on the Swiki.

	Smalltalk-80 - overview of the language

This, I think, should be put on the front page.  "Squeak is based on
*Smalltalk-80*".  Quite a few newbies won't really care.

    The Newbie Home Page

What's the difference between this and the "Learning To Squeak" page?? 
Shouldn't they be the same?  Right now, the Newbie Home Page is pretty
random, and a lot of it isn't really newbie-ish.

    Squeak FAQ

This is already listed right next to "Learning To squeak" on the front
page.  It's on topic, but rather redundent.

    What Is Pluggable Model View Controller
    Fonts in Squeak

These are far from beginner topics, IMHO!


	QuickReference

This is good beginner info, though it is already listed right on the
front page, right next to the "Learning To Squeak" link.  It should be
in one place or the other.

	Morphic Tutorials

This is not beginner material, and it's already got a page for itself,
anyway!

	Chris Phoenix's Tutorial
	Jason Steffler's introduction

These are the first two items I think actually belong on this page:
tutorials that take complete newbies through those first, difficult
steps.


	Medium Sized Essays

I posted this here, but I don't think this is the right place.  These
essays should simply be placed in a tree starting on some sort of
Documentation page.  (see below)

	Squeak-Specific learning resources out on the WWW: 

This is okay, but it needs to be cleaned up and a lot of the
descriptions aren't wonderful.


	Tutorials for other Smalltalks that may be useful:

Excellent.

	Useful Selectors

This looks like a Smalltalk/X tutorial, and so should be put in the
previous section.


	Learning by Doing

This section is confusing.  I like the idea of having more interactive
exercises, but only a couple of the items here actually follow that
guide.




After reading through this a bit, I think the following pages would
cover what we have listed, and would make newbies happy.

	1. Downloading Squeak.  Just like we've already got.

	2. Beginner Tutorials.  List tutorials both for Squeak and for other
Smalltalks.  This is strictly for tutorials that introduce *beginners*
to the system -- beginners really need to be able to find this stuff! 
Possible it could be expanded to "Beginner Information"....

	3. FAQ.  This should be questions that really are frequently asked.  It
should not have thorough coverage of anything in particular -- this is a
catchall for stuff that doesn't fit elsewhere.

	4. Documentation.  A top-level page with sub-pages on specific areas. 
The bulk of documentation pages would fall under here, and the taxonomy
would have to be worked out over time.  Some initial categories would
be: Using the System.  Collections.  Morphic.  MVC.  Exceptions.  EToys.
 Networking.  People keep posting links to pages on various topics
including these, because they know of newbies who want to know about
them.  Well, a newbie might want to know about *any* of them!  They
should go to the Documentation page and start drilling, according to
their interests.


	5. Books.  The current state is okay, though the pages need to be
cleaned up.  We have "Squeak Books" and "Book Reviews".



What do people think?  I like this organization, but it's a significant
overhaul and I don't want to do it if people are attached to the current
state.


Lex Spoon