It would be good to create portions of this Swiki with an encyclopedic writing style, as discussed in the exchange below.
With this style, simple terms and concepts can be defined (and annotated) on a single page. Other pages such as tutorials, Squeak FAQ pages, and other beginner-level pages can then reference these terms as hyperlinks (embedded in the text), without having to worry about re-describing the term.
23 February 2002 - Michael Maloney Discovering Squeak is my attempt to help others learn by documenting my own learning experience. My intent is to use references to pages already on the swiki where appropriate and to write new material where needed. Suggestions / comments are appreciated.
23 February 2002 - Hannes Hirzel
Great that somebody other takes on this brave endeavour! This will help the Squeak community if learners find good material on all levels.
May I suggest that you take on a more encyclopedic writing style, i.e. that you write some sort of lexicon or encyclopedia articles. This makes writing tutorials easier because one does not have to explain everything from scratch as one just can direct people who don't know a concept to the specific entry via a hyperlink.
(For example you can link to Workspace, Inspector, Method Finder, Smalltalk and so on; every concept and tool should have it's own entry, along with the definition, explanation, application hints and examples on all levels; the entry on Object should be expanded considerably, there could be an entry on Message as well.)
On top of this you could write some "guided tours". I don't necessarily consider it a good idea not to use the hypertext approach and be rather booklike.
For example considering OO: for people who are new to this concept you have to explain it rather thoroughly, for a Java programmer a comparison of the oo concepts and an explanation of the specific language used in the Smalltalk programming community. That was actually one of the hardest parts when I learned Smalltalk: every concept had it's new special term not at all related to the languages I had learned before (APL, Pascal, Basic, Assembler, Modula, Oberon, Lisp, SQL, Prolog).
In the last months I've done some editing work on this swiki keeping this in mind. In Notes on specific classes I keep pointers to notes about the use of some classes I consider somehow important or I used in my programming work. A good example of this writing style you'll find if you go to Morphic, or perhaps directly to Morph.
I'd like to encourage you to go on with Discovering Squeak - Contents, but what I would suggest to be there first is a an ordered list of links to already existing entries a newbie is recommended to read. This swiki needs a lot more cross referencing and indexing (as well as refactoring). It contains a lot of useful information but often poorly accessible.
A final note: a encyclopedic writing style has the advantage, that you can give up continuing your work anytime still having made a valuable contribution (and perhaps later if time permits to come back). It as well helps when several authors are working at the same time. And: don't hesitate to rewrite and Refactoring Browser pages.
Some excellent ideas, Hannes. I've also tried to create glossary-like definition links for common terms. (I created the pages for Browser, Workspace, MVC and some others, and I've noticed that similar pages have been created recently by other people, which is good.)
For example, even having a page for something like Red button is very useful, so that you don't always have to re-explain what the red button means in the context of a tutorial or simple description on this swiki.
I agree with your comments that this Swiki still needs a lot more cross-referencing and refactoring, and possibly indexing. (Refactoring the Swiki) I've tried to do this whenever possible, and others should too. I think the Swiki has improved somewhat in terms of cross-referencing, compared with a year or two ago, though.
Probably the ultimate example of an encyclopedic wiki is Wikipedia.
See also Refactoring the Swiki.
