Documentation project (was: Thoughts from an outsider)

J J azreal1977 at hotmail.com
Tue Sep 5 17:07:37 UTC 2006


>From: stéphane ducasse <ducasse at iam.unibe.ch>
>Reply-To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>Subject: Re: Thoughts from an outsider
>Date: Tue, 5 Sep 2006 16:25:26 +0200
>
>>
>>I myself looked at seaside right from the beginning and was never  able to 
>>get my head around it. Actually it is not that difficult,  but because of 
>>lack of documentation, I lost 2 years of possible  using seaside. And on 
>>numerous occasions I have dropped using  squeak for exactly the same 
>>reason. I might have spent 5 more years  in the squeak camp if there were 
>>any documentation for morphic, but  as yet I still cant get anything basic 
>>working to the standard that  I would like.
>
>But you can also help writing class comments or writing tests on what  you 
>learn.
>There is no magic and "you should write documentation" it does not work.
>I would love to have better documentation for Squeak but
>

Well, I was wondering if you guys had any kind of documentation team or
project, but I guess if there was someone would have spoken up by now.

So is anyone interested in starting such a team?  I will contribute what I 
can
in my spare time.  I know no one *wants* to write documentation, but it will
be a good way to learn the systems.

So what we will need will is:
1) A main web site to host it on (can we use squeak.org for this?  how does 
one get started
         adding documentation there?)
2) Some kind of reference manaul like this: 
http://caml.inria.fr/pub/docs/manual-ocaml/index.html
       (does something close exist already?  I have been through many 
'getting started guide's
       but most actually said 'not complete' before you got into the more 
compliated subjects
       like meta programming and meta classes)
3) A list of projects to document.  I don't even know what is out there that 
people need to
       get work done.  It seems to be so all over the place at the moment.
4) We are going to need some people that just sit on the various mailing 
lists and sumarize
       what is going on.  If I am writing the documentation on Pier or 
Seaside, those things are
       moving targets.  If I try to sit on the list and make changes for 
every announcement I
       wont ever release anything.  So we need a person or persons to sit on 
the list and provide
       me or who ever is doing the documentation with a weekly or monthly, 
or whatever works,
       summary of what changes have happened so we can control it more.

And maybe someone else can think of more things.  As a first cut I don't 
want to try to make
UML diagrams or anything like that.  Just getting some nice reference 
manuals out there in a
central place that new people can find it will be a good first cut.





More information about the Squeak-dev mailing list