links to this page:    
View this PageEdit this PageUploads to this PageHistory of this PageTop of the SwikiRecent ChangesSearch the SwikiHelp Guide
Thoughts on documentation
Last updated at 3:17 am UTC on 24 December 2013
refactorMe mergeMe: This is currently a concatination of three old discussion pages. I will summarize it and merge it into Squeak Documentation TeamMatthew Fulmer

  1. organize pages that are marked to be merged into other pages,
  2. mark pages that are in need of updating, whom (if identifiable) should do the updating, and how often. This could be used to set up an automated procedure allowing us to remind ourselves that certain pages may have UseBy Dates associated with them, and prompt the updating of said pages.
Paul Bennett
circa 2007.04.08

From the Squeak mailing list:

Date: Wed, 9 Jun 1999
From: Ralph Johnson
Subject: Re: Documentation

API-level documentation

My experience is that API-level documentation is not as important for Smalltalk as it is for other languages, because it is so easy to read the source.

"Big picture" and cookbook

The kinds of things that need to be documented in Smalltalk are the kinds of things that you can't get easily by reading the source, such as the big picture and how to do a particular task. Part of the motivation of patterns is to be a way to describe the big picture a piece at the time, and also a way to describe how to do a particular task. However, tasks might be better described by the class "cookbook". The VisualWorks Cookbook is a very good example of how to do this for Smalltalk.

Use this wiki!

A wiki is a very good way to capture documentation like this. It is meantime, people can just add things as they realize they are important. A good way to start is just to answer questions as they are asked, and then to organize the answers. There seem to be a lot of questions about Morphic, so that might be a good place to start.

See the Squeak Cookbook for a start.

Suggestions for improving this Swiki

Since no one is directly responsible for checking this page and following up, if you have a serious suggestion for a major change to the Swiki, probably your best bet is to post a suggestion to the Squeak Mailing Lists. If you want to make a more minor change to the Swiki, go ahead, anyone is free to edit it!

Don't let mean people lock the Sandbox.

Actually, don't let mean people lock any page on this swiki. It is my opinion that giving everyone the ability to lock a page is in direct contradiction with swiki's open nature, i.e. the intention that swiki pages should be accessible for anyone to edit. Only the originator of a new page should have the option to lock it at time of creation. (Reversible, of course, by an administrator in case of inappropriate content) los

Pages on this Swiki may be referred to from outside by meaningful URLs. See the help.

For example

(Unfortunately, this is not always reliable. For example, http://wiki.squeak.org/MVC does not link to the right page. Would it be possible to improve ComSwiki so that there is a way to specify the exact page title in the URL? (possibly using %20 for spaces, etc., when necessary) -dew)

When you edit a page don't forget to check if the page is in the right color category.

You can change the color of the page (or rather the color of the button banner).
When you edit a page scroll to the bottom of the page to check it out.

When possible, you can work on improving the content of this Swiki by:

Refactoring the Swiki

A more interesting example is that there might be several different pages which, in the course of a tutorial or basic explanation, explain how to activate the "yellow button" in order to bring up a pop-up menu or similar. (e.g. right-click on a two-button mouse, or option-click on a Mac, or usually middle-click on three-button mouse, etc.)

Instead of repeating this explanation in your page, simply create a page called Yellow button which includes the explanation, and insert the hyperlink in the middle of your text. Then do a quick Search on the swiki to see if there are other pages which mention "yellow button", and refactor those to use links as well.

This is similar to the notion of creating An Encyclopedic Swiki.

There's some good discussion on the C2 patterns wiki about the various ways to refactor wiki pages. The best summary is probably here: http://c2.com/cgi/wiki?RefactoringWikiPages.

These example refactorings are also useful:

(See http://c2.com/cgi/wiki?WhatIsRefactoring for a more general explanation of refactoring as it applies to programming.)

I think one of the main problem in order to refactor the Squeak SWiki is that this Wiki is not really a Wiki ! I mean with a real Wiki, you have WikiWord, WikiBadge, CategoryCategory and some kinds of lightweight authentification with UserName. I think we need to use some WikiBadge or WikiTag (like DeleteMe or RefactorMe). They are very cool features in order to refactor a tangle Wiki. (Ed. note: We have since added these WikiTags, see Administrative tags for wiki pages.)

What we need is also a more deeper integration beetwen the mailing list squeak-dev and the Wiki. Something like WikiMail is a very nice idea! – SergeStinckwich

First, Swiki is a real wiki. I believe that many of the features you describe are avaiable to most WikiWebs, including Swiki. For WikiWord, Swiki simply encloses the words in asterisks. For WikiBadge and WikiTag, all you need is a Wiki that supports lookup of reverse links, which Swiki does quite well. Simply Create a Category page, jump to it, and at the top of the page you should have a drop down list of pages belonging to that category. To illustrate this point, I'll begin a Relevant resources page where we can keep track of the pages that need refactoring. Here is a sample page that I've flagged for refactoring: Pages Needing Refactoring. – Stephen Pair

I completely agree with you. The only missing feature is CapitalizedWikiWords. I like them because they force you to create meaningfull links, not like single word : comment for example. – SergeStinckwich

I disagree on the point about CapitalizedWikiWords. You can argue about the merits of either approach, but the preferred naming convention for Squeak Swiki pages is to use separate words for link/page title phrases. E.g. Squeak Mailing Lists, not SqueakMailingList. (WikiTags are an exception.) Also, single word links such as Workspace, Morphic, image, etc. can be useful in the context of An Encyclopedic Swiki. – Doug Way