
	links to this page:

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.

Earlier

Below is a concatenation of three old discussion pages. I will summarize it and merge it into Squeak Documentation Team –Matthew Fulmer

It is my feeling that we need to create a strong hierarchy to simplify the lists of links layed out through this wiki. Some pages are lists of links to other pages with lists of links. Often the same link is repeated numourous times throughout various lists. It would be better to create a hierarchical list where repetition is minimised, even if it means circumventing other peoples lists. You could still put links to those other lists in a "bibliography" but at times I found myself following links only to end up back at the same wiki page I started at. It would be nice if we could create a place where people would say "hey - let me recommend this link to the Documentatio Team", so a strong centralised list can be maintained. Additionally, I came across a few dead links, and as a wiki is manually updated it would be best to minimise the number of locations the same link is referenced (minimising maintenance issues.
This may be off topic, but Squeak should set up an account with a bookseller. There is no reason why this wiki could not make a little small change off the book recommendations!
Create a hierarchy of all internal (to the wiki- it could be this is the purpose of this page... Refactoring the Swiki) pages that are under the pervue of the Documentation Team. A site map would be great but I see it is something over 5,000 pages. This list can be used to;

organize pages that are marked to be merged into other pages,
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.

Yea, I ran into the same thing. Here I was demonstrating the superoir nature of a SWIKI as a collaboration tool and the damn sandbox is locked! Bad demo. Not nice. An interesting positive idea here would be to create the opposite of a lock. Imagine a way to allow editing but NOT locking as an option for a page. - Stephan B Wessels
I also agree, because I was just locked out of " #20".

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
http://wiki.squeak.org/faq
http://wiki.squeak.org/pws
http://wiki.squeak.org/screenshots
http://wiki.squeak.org/projects

(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:

Pages Needing Refactoring.
Work on making this more of An Encyclopedic Swiki.

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:
http://c2.com/cgi/wiki?RefactorByExtractingToPage
http://c2.com/cgi/wiki?RefactorDontRefer

(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.
SergeStinckwich