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