Goran 3Point4Cleanup Fest
Last updated at 12:46 am UTC on 17 January 2006
10 February 2003
Goran's email of today addresses the urgent need for more and better documenation in Squeak.
Here are highlights of his recommendations:
- Code cleanup week
- Write a design for "Magic Book"
- List core classes to cleanup
- Write unit tests
- Designate a Coordinator (need a volunteer) Documentation Project
I support these activities in whatever form. Here is my little "wish
list" for what we could/should do:
1. Do a "cleanup week" where we pick a corner of the image and clean it
up in all respects (class comments, unit tests, example code and perhaps
even tutorial/howto/writeup). Put a "janitor" in charge set a date and
let's go for it. Cleaning the house is much more fun if we are all doing
it at the same time and intense! I would also really favour using IRC
during this week to get the blood really pumping (the new IRC client
2. Somebody starts designing the so called "Magic book". No code nor
content, just a proposal on how it can work and look - such a tool
really needs to get "anchored" in the community before we start cranking
out code. Note that there are especially two very challenging issues:
1. How to make the UI really comfy.
2. How to make it play together with SqueakMap, all the unit tests (as
we planned) and how to make it NOT bloat the image (using Projects
cleverly might be one ingredience).
3. Write down a sequential list of core classes that we intend to clean
up (class comment, unit tests, example code) and let people "sign up" on
that list. BUT... you can only sign up on the "next in line"! Why? Well,
to force us into a work process where we can easily see if we are
covering any ground. Well, just an idea but if people start working all
over the place then it will feel like we aren't making progress.
Anyway - I know the above is focusing on class comments, example code
and unit tests. This doesn't mean the other tutorial/introductory/howto
stuff etc isn't important. As Hannes wrote (I think) keep working on the
swiki and then later we can think about the Magic book when there is one
available to fill with content. :-) As someone said after all "Content
Unfortunately I will not be able to help out more than on this list -
but you all have my support and probably the rest of the Guides too. If
someone of you REALLY are going to get into this documentation project
(I know that it is very easy to become distracted and bored) :-) then I
would consider creating a role for it and putting that "in public" on:
That person would act as a coordinator for these activities and make
sure we are moving forward. Well, what can I say - I simply like
personal responsibility - it works like a "conscious based motivator".