[Cuis-dev] On the importance of documentation

H. Hirzel hannes.hirzel at gmail.com
Tue May 13 12:29:05 PDT 2025


20 hours of video! With still 800plus views in the last one.

But unfortunately no structure is visible. Just labeled episode 1 to 11.

Maybe somebody has made notes about the structure?

BTW the videos are 4 years old...


On 13/05/2025 9:13 pm, H. Hirzel wrote:
>
> Good idea, the link and note should be included in 
> https://github.com/drCuis
>
> Where?
>
> On 13/05/2025 1:59 pm, Ezequiel Birman via Cuis-dev wrote:
>> It is in spanish, only not *written*, rather there are playlists made 
>> by Hernán Wilkinson and Nahuel Garbezza at 
>> https://sites.google.com/view/cuis-university/tutoriales; I think it 
>> is possible to turn YouTube's auto-translate feature on and make 
>> sense of it most of the time.
>>
>> -- 
>> Eze
>>
>> On Mon, 12 May 2025 at 18:29, H. Hirzel via Cuis-dev 
>> <cuis-dev at lists.cuis.st> wrote:
>>
>>     Or maybe a lower hanging fruit:
>>
>>     Is the Cuis University material written in Spanish? I guess it
>>     includes
>>     a chapter on the use of the SystemBrowser and other related tools
>>
>>     Under which license does it come?
>>
>>     It could be translated to English by automatic means and then
>>     post-edited by an English native speaker.
>>
>>     --Hannes
>>
>>     On 12/05/2025 6:56 pm, H. Hirzel wrote:
>>     > On 12/05/2025 2:32 pm, H. Fernandes via Cuis-dev wrote:
>>     >> I completely agree, I was exactly thinking about that recently.
>>     >>
>>     >> Such documentation will go as a tutorial documentation. Do you
>>     know
>>     >> any such doc.
>>     >
>>     > Squeak 6.0 by example
>>     >
>>     >
>>     https://github.com/hpi-swa-lab/SqueakByExample-english/releases/download/6.0/SBE-6.0.pdf
>>
>>     >
>>     >
>>     > has a chapter on 'The Squeak Programming Environment' where
>>     Browser,
>>     > Workspace, Transcript, Message Name tool, Method finder, Process
>>     > browser, Debugger are explained.
>>     >
>>     > The license is
>>     >
>>     > e Creative Commons Attribution-ShareAlike
>>     > 3.0 Unported license.
>>     >
>>     > So I assume that chapter may be lifted out from there, screen
>>     shots
>>     > exchanged and text adapted where necessary.
>>     >
>>     > --Hannes
>>     >
>>     >
>>     >
>>     >>
>>     >> Dr. Geo -- http://gnu.org/s/dr-geo
>>     >>
>>     >> ----- Luciano Notarfrancesco <luchiano at gmail.com
>>     <mailto:lt%3Bluchiano at gmail.com>> a écrit :
>>     >>> Hi Hilaire,
>>     >>> Thanks for the interesting reflections, and for the
>>     documentation
>>     >>> efforts.
>>     >>> I think perhaps the first thing newbies should learn is to
>>     explore the
>>     >>> system, to find out the details of how it works,
>>     >>> browser/senders/implementors/messages. Personally, every time
>>     I want
>>     >>> to do
>>     >>> something in Cuis and I don’t know how, I just use these tools,
>>     >>> explore,
>>     >>> search messages (guessing parts of selectors), find examples
>>     of use
>>     >>> in the
>>     >>> image, perhaps change something and see how the system
>>     reacts, etc.
>>     >>> More
>>     >>> specific documentation is great, of course, but as a first
>>     step I would
>>     >>> point any newbie trying to do anything with Cuis to first
>>     learn the
>>     >>> tools
>>     >>> to explore the system. What do you think?
>>     >>>
>>     >>>
>>     >>> On Thu, May 8, 2025 at 15:59 Hilaire Fernandes via Cuis-dev <
>>     >>> cuis-dev at lists.cuis.st> wrote:
>>     >>>
>>     >>>> Some interesting reflections on documentation in the NumPy
>>     community:
>>     >>>>
>>     >>>>
>>     >>>>
>>     https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community
>>
>>     >>>>
>>     >>>>
>>     >>>> The text is a bit long, so I pasted below some interesting
>>     extracts.
>>     >>>>
>>     >>>>
>>     >>>> *Why documentation is important. *
>>     >>>>
>>     >>>> [...] Having official high-level documentation written using
>>     >>>> up-to-date
>>     >>>> content and techniques will certainly mean more users (and
>>     >>>> developers/contributors) are involved in the NumPy community.
>>     >>>>
>>     >>>> So, if everybody agrees on its importance, why is it so hard to
>>     >>>> write good
>>     >>>> documentation?
>>     >>>>
>>     >>>>
>>     >>>>
>>     >>>> *What the corporate world does. *
>>     >>>>
>>     >>>> If we look at proprietary or com pany-backed software
>>     projects, often
>>     >>>> professional technical writers are working on the docs. Having
>>     >>>> access to
>>     >>>> these professionals to do the documentation can make a huge
>>     >>>> difference.
>>     >>>> [...]
>>     >>>>
>>     >>>>
>>     >>>>
>>     >>>> *What is the tendency in free software communities. *
>>     >>>>
>>     >>>> [..] As I got more involved in the open source world, I
>>     realized
>>     >>>> that the
>>     >>>> people writing docs were not only invisible but were sometimes
>>     >>>> actively
>>     >>>> discouraged. There is even a differentiation in naming such
>>     >>>> contributions;
>>     >>>> have you ever heard of a "core docs developer"? [..] *Even
>>     when the
>>     >>>> community is welcoming, documentation is often seen as a
>>     "good first
>>     >>>> issue", meaning that the docs end up being written by the least
>>     >>>> experienced
>>     >>>> contributors in the community. [..] However, it may transfer the
>>     >>>> responsibility of one of the most crucial aspects of any
>>     project to
>>     >>>> novice
>>     >>>> users, who have neither the knowledge or the experience to make
>>     >>>> decisions
>>     >>>> about it.*
>>     >>>>
>>     >>>> -- http://mamot.fr/@drgeo
>>     >>>>
>>     >>>> --
>>     >>>> Cuis-dev mailing list
>>     >>>> Cuis-dev at lists.cuis.st
>>     >>>> https://lists.cuis.st/mailman/listinfo/cuis-dev
>>     >>>>
>>     -- 
>>     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/20250513/d499f395/attachment-0001.htm>


More information about the Cuis-dev mailing list