[Squeak-doc] General thoughts...

[Matthew Fulmer]

On Thu, Apr 05, 2007 at 12:03:40AM -0700, Paul Bennett wrote:
> 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?

Pier is way more than a wiki. Check it out:
http://wiki.squeak.org/squeak/3700

I will look into those.

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

I immagine that once there is enough maintainable documentation,
peer pressure will arise, causing developers to expect
documentation just as they now expect SUnit tests.

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

I just created a roadmap proposal. It is a separate email,
cross-posted to squeak-dev and squeak-doc

-- 
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808