[Cuis-dev] Documenting...

[Ezequiel Birman]

Hi Hillaire!

I still have to finish reading TCB but even at this point, it is quite
clear to me that it is a labour of love, and that you and the other
authors are very conscious that it could be detrimental to include the
kitchen sink.

I also think it could be a good candidate for a dynabook. I'd love to
collaborate on that, even if I haven't finished all the exercises yet.

I am in no position to review TCB's content and extent yet. For the time
being, it seems to me that it is good as it is.

Re. Wikis, any would do. During the last week, I've been testing different
TiddlyWiki versions (some are better for multiple users) and I find that
conceptually, TiddlyWiki shares with Smalltalk this idea of being
self-contained, see Intertwingling the Tiddlywiki with Erlang
<https://www.youtube.com/watch?v=Uv1UfLPK7_Q>. Nevertheless, I think that
the ideal medium would be something that runs *in* Cuis and that at the
same time could be rendered as a web site. Could Erudite do that?

Some topics:

   1. An in-depth customization guide
   2. A tutorial for the simplest web application

-- 
Eze


El mié, 2 ago 2023 a la(s) 12:02, Hilaire Fernandes via Cuis-dev (
cuis-dev at lists.cuis.st) escribió:

> 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
> --
> Cuis-dev mailing list
> Cuis-dev at lists.cuis.st
> https://lists.cuis.st/mailman/listinfo/cuis-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20230802/b98c13fe/attachment.htm>