[Cuis-dev] Documenting Cuis

[Juan Vuletich]

Hi Hilaire,

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.

Just my 2 cents.

Cheers,


On 7/5/2020 3:05 PM, Hilaire Fernandes via Cuis-dev wrote:
>
> Hi,
>
> Cuis is documented with bits found there and there, it is not easy for 
> new comers. Several time, after searching on Cuis or asking on the 
> list, I felt like a want to write a small documentation notes on a 
> recent finding so it can be useful for other. So far I didn't and it 
> is a waste, pretty sure the same occurred to you as well.
>
> We already have https://github.com/Cuis-Smalltalk/Learning-Cuis and 
> also https://github.com/Cuis-Smalltalk/CodeExamples with valuable 
> contents! If I miss any, please tell.
>
> What about more structured documentation, like a book, (with content 
> related to LeaningCuis and CodeExample). We could each other insert 
> our knowledge in documentation notes into it. I think I could spend 30 
> min/day on such a project.
>
> IMHO, on-line editing with capability to output printed book, may be 
> several ones, for Lulu will be a nice achievement by the community. It 
> will give more visibility to Cuis too.
> Of course inserting documentation notes does not make a book but it 
> gives valuable *incentive**s* and *directions* to expend in valuable 
> documentation.
>
> Bellow my suggestions for a table of contents.  We could insert into 
> documentations note and expand it later as documentation paragraphs 
> (we can capitalize on the Squeak/Pharo by Examples too, for some 
> Smalltalk generic contents).
>
> Any opinion? Suggestion for the table of contents? At which place 
> could we do the effort? Which tools to use?
>
> Hilaire
>
> ------------------------------------------------------------------------
> *A. Basic Cuis-Smalltalk*
>
>     _Getting started _
>
>         Installing Cuis-Smalltalk
>         Starting Cuis-Smalltalk
>         Configuring Cuis-Smalltalk environment
>         Writing your first script
>         Introduction to the system class
>
>     _Writing your first application_
>             An excuse for a tour in Cuis world (Browser, Inspector)
>
>     _Understanding the basic Cuis' model_
>
>         Syntax
>         *Statements as blocks and messages send*
>         Basic classes
>         Collections
>
>     _Writing your second application
>     _
>
>         A second excuse for a tour in Cuis World (Debugger, Changset)
>
>     _Cuising with Style (aka best practices)_
>
>         Variable/Comments/Method/Scope/Refactoring...
>         Common design patterns
>         ...
>
> *B. Advanced Cuis-Smalltalk*
>
>     _Cuis-Smalltalk code management
>
>     Going visual_
>
>         The Morph system
>         Composing widget with layout
>         Graphic vectors engine
>
>     _The object model_
>
>     _Testing your code_
>
>     _Streams_
>
>     _Reflection_
>
>     .../...
>
>
> -- 
> GNU Dr. Geo
> http://drgeo.eu
> https://pouet.chapril.org/@hilaire


-- 
Juan Vuletich
www.cuis-smalltalk.org
https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev
https://github.com/jvuletich
https://www.linkedin.com/in/juan-vuletich-75611b3
@JuanVuletich

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