[Cuis-dev] On the importance of documentation

[H. Hirzel]

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
>>>>