Documentation [was: Morphic tutorial]

Stephane Ducasse ducasse at iam.unibe.ch
Wed Feb 5 18:24:17 UTC 2003


Hi chris

The first cool thing to do would be to have: a class comment for each  
class and
two examples on the class side.

With that included into the Squeak image this would be great.
Note that the examples could be SUnitied so that we could be 100% sure  
that they are correct and the classes is up and running. But apparently  
other community understood what we are missing all the time.

Stef

On Wednesday, February 5, 2003, at 02:24 PM, Chris Burkert wrote:

> 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/
>
>
>
Prof. Dr. Stéphane DUCASSE (ducasse at iam.unibe.ch)  
http://www.iam.unibe.ch/~ducasse/
  "if you knew today was your last day on earth, what would you do
  different? ... especially if, by doing something different, today
  might not be your last day on earth" Calvin&Hobbes




More information about the Squeak-dev mailing list