[Cuis-dev] On the importance of documentation

[H. Hirzel]

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