shane at shaneroberts.com wrote:
> 
> ...
> I think we have to be careful about "archiving" the swiki pages, because I notice
> they are often referenced by members of the list, and we could produce a lot of
> broken links in people's email if we remove pages (or rename their URL).

Actually this is not quite true for renaming.  Renaming a swiki page does not
cause any broken links, which is another nice thing about swikis.

For example, if you renamed the "All Projects" page to "All Projects
(archive)", all of the other swiki pages which referenced this page would
automatically update their links from *All Projects* to *All Projects
(archive)*, so there would be no broken links within the swiki.  And from
outside of the swiki, people usually use URLs of the form
http://minnow.cc.gatech.edu/squeak/1406 to reference swiki pages, and this
link would not change, so these links would still work as well.

(There's yet another way to reference swiki pages externally, by name.  For
example, http://minnow.cc.gatech.edu/squeak/allProjects will bring up the All
Projects page.  There seems to be some sort of wildcard searching going on
with this type of link, so that if I rename the page to "All Projects
(archive)", the above link works, but if I rename it to "asdfasdf", it no
longer works.  In any case, this type of link seems to be rarely used.)

(By the way, I used "All Projects (archive)" as an example because I think
that page is on the verge of being obsolete, now that SqueakMap is the central
point for all Squeak applications.  Actually, I wonder if something like "All
Projects (old)" or "All Projects (obsolete)" or similar might be better... I'm
not sure if the word "archive" would make me realize right away that I was
looking at old information.)

So in summary, we should not hold back on renaming swiki pages if it's the
right thing to do.

> I am new to Squeak and Smalltalk, but I have now discovered (with Goran's
> encouragement) that the Swiki is VERY useful.
> 
> So I agree the Swiki should be maintained, upgraded, and used.

Yes. :-)

One other page (which Hannes may have already mentioned) that has useful ideas
on how the Swiki can be used for documentation is the "An Encyclopedic Swiki"
page:

http://minnow.cc.gatech.edu/squeak/2348

With the "Squeak Documentation Project" page, it is worth thinking about how
this page differs in content from the top Swiki page
(http://minnow.cc.gatech.edu/squeak), and avoid too much duplication of
content.  I guess the SDP page attempts to organize information on Squeak
itself, while the top Swiki page attempts to organize information on Squeak
itself, but also information on Squeak's history/future, the community,
projects, etc.

Ah, I see Lex Spoon has already added a comment about this to the page.

But in any case, this page (with its hierarchy form) looks like it could be a
potentially better organization of links than the stuff under the
"Documentation" heading on the top swiki page.  So, keep at it. :-)

> But I also agree with the suggestion that embedded documentation in Squeak is
> preferable, and that of course we need to improve code comments, etc.
> In particular I think the "magic book" has the potential to introduce naïve users
> and new developers to Squeak in an exciting way.

I had a related idea about improving the class comment situation in Squeak
awhile ago:  In the class browser, you could have a link at the bottom of the
class comment text (or somewhere else in the browser UI) which would open
Scamper to the Swiki page with that class name.  That Swiki page could then
include the class comment, examples, etc., and be more easily updated by
everyone.  As an example, there's already much better information on
AlignmentMorph at http://minnow.cc.gatech.edu/squeak/alignmentMorph than there
is in the current class comment. :-)

One problem with this at the moment is that there is not a reliable way to
externally link to the name of a Swiki page (which I mentioned above... it
does some sort of wildcard matching which doesn't always bring up the expected
page).  Perhaps I will make an enhancement request for ComSwiki about this.
:-)

Awhile ago, someone else had an idea of creating a class comment database, and
partly implemented it.  This might also work well, although I kind of like the
brain-dead simplicity of the Swiki solution, which already has its built-in
editing and hyperlinking features which are well-known to most of the
community, and even has a number of class comments already.

Anyway, those are some random thoughts for now.

- Doug Way