[Cuis-dev] Documenting Cuis

[Hilaire Fernandes]

Hi Juan,

The license could be Creative Common Attribution-Share Alike as the 
Squeak/Pharo by Example books from where we could pickup some parts, the 
Smalltalk ones (I wrote the original Morphic chapter, in French).

I briefly took a look at documentation systems, Spinx[1] looks 
interesting and largely used. It will require some effort to export to 
the Euridite wiki like original editing format though. There are 
numerous use case examples to visit[2].

[1] https://www.sphinx-doc.org/en/master/

[2] https://www.sphinx-doc.org/en/master/examples.html


Yes to a preface explaining the origin of Cuis!

Regarding the "Configuring Cuis Smalltalk environment" section, in my 
mind, it is a tour to the Cuis GUI to customize it to the personal 
tastes of the user (font, size, theme, window placement), so not much 
technical.

For us, Morphic is like breathing air, very common and basic. Is it the 
case for a  Cuis/Smalltalk neophyte? I think no. That's why I pushed it 
to the second part of the book. Nevertheless, the first part could write 
about Morphic, in the two application examples, but not exhaustively.

We should question our self, what is the target audience of the book? I 
was thinking about a reader with little or no experience in programming, 
but interested on the topic. It is important to decide on the typical 
reader for the book to get the content right for. Smalltalkers, coming 
or curious about Cuis, will likely have little benefit of the book; they 
are capable to figure out by themselves how to start and use fluently 
Cuis. The vast majority of prospective readers to seduce have zero 
knowledge about Smalltalk and Cuis. This gives some perspective.

Hilaire


Le 06/07/2020 à 16:27, Juan Vuletich a écrit :
> I don't have a strong opinion on the best way to document Cuis. I 
> think a book would be great addition to the Cuis world, and I'm 
> willing to help. I also think that is the license of the contents is 
> appropriate, stuff we write could be reused in other forms (like 
> active essays in the image).
>
> WRT to the table of contents, I'd add a preface explaining what Cuis 
> (and Smalltalk-80) is all about, and as little space on technicalities 
> as possible. For instance, I don't think that "Configuring Cuis 
> Smalltalk environment" is needed, and would collaps Installing... and 
> Starting... in a single hopefully short text.
>
> I'd also avoid waiting until "advanced topics" to tell a bit about 
> Morphic. The UI and the environment are central to Smalltalk, and 
> Morphic is central to Cuis.

-- 
GNU Dr. Geo
http://drgeo.eu
https://pouet.chapril.org/@hilaire

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