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 11:27 pm UTC on 17 August 2018
refactorMe mergeMe:

2018 summary: How should documentation be done

A method ought to be commented as to what it is meant to do. That is not always what the code actually does, for example during early stages of development. It would be nice if the comment explained any known limitations or likely error conditions.

A class should be commented to explain its intent, along with what ivars are used for and maybe even the sources for any interesting algorithms used. Mentioning other related classes and how they help might be nice.

Add a page to the HelpBrowser system. Take a look at the Help browser (main menu -> Help) and look at the 'Help on Help' section, in particular the 'Implementation' part. This is a good way to document something about systems and applications rather than the classes and code implementing them. We need a lot more help pages.

Add a page or ten to the swiki. This is a good place to be more expansive since it doesn't take any space in the image or sources. And you can include pictures which we don't seem to be able to do in the HelpBrowser (yet).

Swiki pages are accessible within the HelpBrowser. Thus code on Swiki pages may be directly executed from within the image in the sense of an Active Essay.


Below is a concatenation 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

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

First this Swiki is a real wiki.
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.