[Cuis-dev] Documenting...

[Bernhard Pieber]

Hi,

I note that recently an updated version of Squeak by Example was published. It is maintained here:
https://github.com/hpi-swa-lab/SqueakByExample-english

Here is the link to the PDF:
https://github.com/hpi-swa-lab/SqueakByExample-english/releases/tag/6.0

I just skimmed it and I am sure a lot of chapters would be almost identical. If we just took those we could probably save a lot of work. OTOH, we would definitely need Cuis specific chapters on Morphic, VectorGraphics, Packages, Files, and Unicode. So, to make a Cuis by Example would still be a lot of work. Personally, I do really like that the output is a PDF.

Cheers,
Bernhard


> Am 02.08.2023 um 13:01 schrieb Hilaire Fernandes via Cuis-dev <cuis-dev at lists.cuis.st>:
> 
> 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 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 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