[Cuis-dev] On the importance of documentation

[Ezequiel Birman]

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> 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/743be744/attachment.htm>