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
|