[Cuis-dev] On the importance of documentation

[H. Hirzel]

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/254a7952/attachment.htm>