[Squeak-doc] General thoughts...

[Paul Bennett]

Hi,

I'm still getting my head around the magnitude of what I have just  
volunteered to be a part of. I've griped and groaned before about the  
seeming lack of information about Squeak / Smalltalk but after  
perusing the wiki I am astounded by how much is there. Though at this  
point it's usefulness to me is not determined.

Having said that, the following is a regurgitation of what has so far  
passed through my noob synapses about the topic of Documentation and  
I offer them as points of discussion...

We are working on two concurrent, yet associated, projects...
* Squeak Documentation Project
* Squeak Tutorial Project (listed as the first project of the  
Documentation Team)

These questions came to mind.

1) Is the current wiki system suitable  to handle the end result, and  
if not, is there something available in Squeak for it?
There was a little discussion today in IRC about it. And there is a  
desire to see magicbook created. But we only have a wiki right now  
and my thoughts currently are around my understanding that a Wiki is  
a fairly statically structured system. I sense that what we are  
looking to produce is going to be significantly dynamic. A static  
system is going to require a huge amount of effort in maintenance -  
something we don't seem to access to(yet?!).
Also, to get the ideas flowing, what do you think about using concept  
maps to lay out access to information?
Check this link out....  http://www.eiffel.com/developers/learning_maps/
and how about this... http://cmap.ihmc.us/
Perhaps these are tools that could be developed in Squeak?

2) Documenting everything in Squeak is a big task. BIG! At least it  
looks that way to me. Do we want to include documentation for non- 
core projects like Seaside and Pier? I ask this because documenting  
and Tutorialising those two projects is what brought me to the  
Documentation group to begin with. I can envision a core  
documentation team assisting with project members documenting their  
product, but I sense most of them have their own pages they would  
maintain and the core Documentation team might prompt them annually  
to add / change material where necessary.

3) Who are the users of the wiki? What do they want from it? How are  
we going to provide for those needs?
Some initial definitions I come up with are...
Non-Programer
  	AKA newbies (no programming experience at all)
	
Programmers
	Switchers (from other languages or other VM's)
	Intermediate
	Advanced (do they even visit the wiki?)

4) Presentation of information is almost as important as the content  
of that information. So thought needs to be given to this area. So  
look and feel of the wiki adds value to the material presented.


5) We should define the information we want to collect when entering  
an article/tutorial/link to the wiki. This would act as a guideline  
for ways to search it later, and to sort by usefuleness. Eg,  
Published date (eg: older articles might get a lower weighting),  
Title, Author(s), Topic, Tags, Abstract.


Other Random Thoughts
--------------------------------
* Have a ratings & comments system for articles (ratings can only be  
applied by registered Squeakers)
* Tags that can be associated with an article so that filtered  
searches are available


I believe in the KISS principle, but the above thoughts might provide  
for a discussion of a roadmap.

Regards
Paul