[Cuis-dev] Documenting...

[Hilaire Fernandes]

Hi Folks,

Yeah again this boring topic of documenting... But for a community to 
grow you need some documentation.

 From the feedback we regularly receive in the mailing list, we can say 
the The Cuis Book <https://cuis-smalltalk.github.io/TheCuisBook/> was 
and is a worthy effort. With Ken and Juan we discussed about the target 
audience, its contents and scope, and also its limitation. It does not 
present every facet of Cuis, it is a gentle introduction to basic 
programming, Smalltalk and Cuis, a sort of appetizer.

I would like to discuss with you the next step in term of documentation. 
Indeed there are many topics we do not cover in detail or at all which 
could be useful to improve the experience of the developers. Among them 
Layout, VectorGraphics, GUI building, Event, Error handling, etc.

Nevertheless, there is already Learning-Cuis 
<https://github.com/Cuis-Smalltalk/Learning-Cuis> documentation, but I 
have doubt about github wiki for large documentation, may be I am wrong. 
There is also the embedded documentation from the Terse Guide. These 
useful documentations are in different places and formats, it does not 
ease the access to documentation.

We should get it all in one place: easy to access and to contribute too. 
Therefore as a medium we may want to use something flexible as a wiki or 
equivalent.

Regarding its content, we can discuss here the topics most of you will 
be interested by, after all this is the best way to have meaningful 
documentation. Also discussing how to structure the contents to prevent 
it to become too quickly a mess. Such contents will be a place of 
reference when a user needs some information or know how. In my opinion, 
such documentation is fundamental to see a growing Cuis community.

Concerning contributions, all users are concerned. Even a casual, new 
user of Cuis who has just finished reading the Cuis book could 
contribute. In fact, documenting a topic you are learning is an awesome 
mean for deeper learning. In education this is something we do often 
through learning by the pair.

Let's the discussion begin :

- Topics of interest

- Format, place  to document


Hilaire
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20230802/a61e89b5/attachment.htm>