[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