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 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.
From the Squeak mailing list:
Date: Wed, 9 Jun 1999
From: Ralph Johnson
Subject: Re: 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.
- 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.
(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