Documentation [was: Morphic tutorial]
Gary Fisher
gafisher at sprynet.com
Wed Feb 5 13:54:51 UTC 2003
Hi, Chris!
A Documentation Swiki makes sense, but I'd prefer to see the "Squibes"
remain on the main list, both to minimize cross-posting and to ensure
everyone's kept up to date both on development and on documentation.
Perhaps a [DOC] tag could flag particularly "documentation-oriented"
messages, but there's great value in keeping everyone in close
communication.
That's my vote. (-:
Gary Fisher
----- Original Message -----
From: Chris Burkert
To: The general-purpose Squeak developers list
Sent: Wednesday, February 05, 2003 8:24 AM
Subject: Documentation [was: Morphic tutorial]
Hi List
I think there are some people (I'll call them writers), who could write
some documentation, even if they are newbies. For example I would write
down some things about squeak if I had some guys (I'll call them
leaders) who could tell me where to start and they would point out the
main ideas.
So here are my suggestions:
- let us create a seperate mailinglist for documentation
This list should be read by those leaders and by the writers.
You may say there aren't much. Maybe ... but I'm one of those!
Let's turn the enthusiasm of newbies into good documentation
work. Let's integrate newbies. Give them the opportunity to
explore a little piece of squeak. This way newbies aren't
overcharged and can look inside the world of squeak. On the
other hand the leaders can work on the front development and
don't have to answer all those newbie questions. They only
have to guide one or two of the writers a little bit.
- let us create a hierarchical overwiew about the main concepts
in squeak for example a well formed swikipage. This page should
have all the links to documentation. This page should be visited
from the leaders and the writers one time a year by everyone.
Delete or update Deadlinks! Order Documentationlinks in a
obvious 'right' order (think of old and obsolete pages at last).
It should be formatted in some kind of corporate design. One look
and you will know if this documentation can answer what you're
searching for (see next point).
- every piece of documentation should have some attributes
+ a short overview about the subject
+ when was it written
+ when was it changed the last time
+ who is/are the writer/s
+ who is/are the leader/s
+ what kind of documentation is it ?
(tutorial, architecture, ...)
+ what is the related squeak version
+ is it obsolete ? -> point out the actual way of doing this!
+ ...
Maybe you find more points ... well let's collect them. If we want to
make squeak more popular (and I hope that everybody of us wants this),
then integrate the people who are willing to do something. Don't tell
them that there is a lack of documentation ... this lack can be found in
every thing in the world. Get them to contribute their ideas and guide
them. This is Extreme Learning !!! Learn with the help of others.
I'm willing to do something. So tell me what!
Let's talk about the topic and collect the main ideas. This should point
out a good way of minimizing this lack of documentation and, by the way,
will help to educate new Squeakers that may become leaders in the future.
Regards
Chris Burkert
--
------------------------------------------------------------------------
Student of applied Computer Science at Chemnitz University of Technology
http://www.chrisburkert.de/ chbu at hrz.tu-chemnitz.de
------------------------------------------------------------------------
"I invented the term Object-Oriented, and I can tell you I did not have
C++ in mind." - Alan Kay --> http://www.whysmalltalk.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20030205/8233dae7/attachment.htm
More information about the Squeak-dev
mailing list
|