Hi All,
This is the official unofficial launch of the latest round of 
documentation effort.

I found a page on the swiki that has not been changed since 1999 
called:  "Documentation - tasks to do"

It is:
http://minnow.cc.gatech.edu/squeak/808

Let's start using this as a central Swiki scratchpad for cooperation 
on the documentation project.

Also, of course, posts to the list:
squeak-dev at lists.squeakfoundation.org

with subject lines beginning:
[DOCS]

will provide a list thread that tracks discussion.

There is a more formal outline for the project on the swiki at:
http://minnow.cc.gatech.edu/squeak/2983

This is the "SDP" Squeak Documentation Project page.

As of now four members of the list (including myself) have 
expressed immediate interest in working on documentation.
I am posting their names and email address on the above swiki 
page, and below.  If you don't want to show up on the swiki, please 
edit the page and remove yourself.

Shane Roberts(me) shane at shaneroberts.com
Brent Vukmer  bvukmer at blackboard.com
Hannes Hirzel hannes.hirzel.squeaklist at bluewin.ch
Lic. Edgar J. De Cleene edgardec2001 at yahoo.com.arj

If I have forgotten anyone, my apologies, please add your name to 
the swiki page.

Since the "to do" swiki page is a scratchpad, feel free to make a 
mess of it, add all your suggestions and comments there, and we 
will sort them out as we go.

To reduce clutter on the swiki in general, I suggest we make every 
effort to edit and clean up existing pages, rather than make new 
ones.  I don't think deleting pages is good, broken links are a drag.

The comment has been made that "external documentation is 
immediately obsolete".  This is only partly true.  The Smalltalk 
language is stable, so any discussions on the swiki of this sort, will 
not be obsolesced.  Otherwise I agree, most of the documentation 
should be within Squeak, and kept up to date (somehow).  The 
swiki is useful, but people may not find it easily, so the 
documentation needs to be in Squeak.

Following are seven main ideas that have been discussed on the 
list to improve documentation:

*******
Write SUnit tests - this verifies that what is documented, executes, 
as well as providing documentation.

More Code Comments - any questions?

A "Magic Book" - documentation within Squeak which uses its 
multi-media capabilities to illustrate the use and power of Squeak 
for both developers and naïve users.

Code Comment "Scooper" - a tool which sweeps all the code 
comments into a format which allows them to be scanned and 
cross referenced (hyperlinked)  easily (more easily than using the 
existing browsers).  The idea here being to provide a different 
cognitive "view" on the code, not to add yet another browser.  So it 
needs to be powerful enough to justify its existence.

Don't Bloat The Image - new documentation and tools should not 
add yet more bloat to the image.  Code comments are fine, they 
don't add bloat.  Other new tools and documentation need to be 
very small, or optional to the standard contents of the image.  For 
naïve users we may want something like a "Take the Tour" button, 
which loads the magic book.  I realize there is already a "tour" so 
this could be added.

Clean Up the Swiki - review the swiki and update or clean up its 
documentation.

Literate Squeaking - see:
http://minnow.cc.gatech.edu/squeak/310

*******

I have scanned the swiki for pages dealing specifically with 
documentation issues.  Those pages are listed below, as well as on 
the "to do" page discussed at the top of this post:
http://minnow.cc.gatech.edu/squeak/808

http://minnow.cc.gatech.edu/squeak/471
http://minnow.cc.gatech.edu/squeak/812
http://minnow.cc.gatech.edu/squeak/400
http://minnow.cc.gatech.edu/squeak/791
http://minnow.cc.gatech.edu/squeak/766
http://minnow.cc.gatech.edu/squeak/377
http://minnow.cc.gatech.edu/squeak/804
http://minnow.cc.gatech.edu/squeak/310
http://minnow.cc.gatech.edu/squeak/2983
http://minnow.cc.gatech.edu/squeak/41
http://minnow.cc.gatech.edu/squeak/264
http://minnow.cc.gatech.edu/squeak/help
http://minnow.cc.gatech.edu/squeak/807

If you are new to the Squeak swiki, go here:
http://minnow.cc.gatech.edu/squeak/help

In general my pet peave on the web, and with white papers, 
articles, etc. is NO DATE.  It is so easy to timestamp your writing 
so that it is in context.  Writing that says "today we are" or "next 
month" or "next year" and has no date on it, is meaningless.  Much 
of technical writing is useless after a couple of years, but with no 
date on it, how would you know its currency?

Code comments are exempt of course.

See you on the swiki...

Shane