<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
I fully agree with this.<br>
<br>
Documenting Smalltalk is not the same as documenting a black box
library. People should be encouraged to explore the system by
themselves. Separate documentation should focus especially on the
concepts and ideas that can not be easily discovered in that way.<br>
<br>
Thanks,<br>
<br>
On 5/12/2025 4:10 AM, Luciano Notarfrancesco via Cuis-dev wrote:
<blockquote
cite="mid:CAL5GDypLGSPWi-RO8ULMN9C1s5cQq=mxj=RViGoFpxzigKJhJQ@mail.gmail.com"
type="cite">
<div dir="auto">Hi Hilaire,</div>
<div dir="auto">Thanks for the interesting reflections, and for
the documentation efforts.</div>
<div dir="auto">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?</div>
<div dir="auto"><br>
</div>
<div><br>
<div class="gmail_quote gmail_quote_container">
<div dir="ltr" class="gmail_attr">On Thu, May 8, 2025 at 15:59
Hilaire Fernandes via Cuis-dev <<a moz-do-not-send="true"
href="mailto:cuis-dev@lists.cuis.st">cuis-dev@lists.cuis.st</a>>
wrote:<br>
</div>
<blockquote class="gmail_quote" style="margin: 0px 0px 0px
0.8ex; border-left: 1px solid rgb(204, 204, 204);
padding-left: 1ex;">
<div text="#000000" bgcolor="#FFFFFF">
<p><font style="color: rgb(0, 0, 0);" size="4">Some
interesting reflections on documentation in the NumPy
community:<br>
</font></p>
<p><font style="color: rgb(0, 0, 0);" size="4"><a
moz-do-not-send="true"
href="https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community"
target="_blank">https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community</a></font></p>
<p><font style="color: rgb(0, 0, 0);" size="4">The text is
a bit long, so I pasted below some interesting
extracts.</font></p>
<p><b><font style="color: rgb(0, 0, 0);" size="4">Why
documentation is important.<br>
</font></b></p>
<blockquote>
<p><cite>[...] 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.</cite> </p>
<p><cite>So, if everybody agrees on its importance, why
is it so hard to write good documentation?</cite></p>
</blockquote>
<p><font style="color: rgb(0, 0, 0);" size="4"><br>
</font></p>
<p><b><font style="color: rgb(0, 0, 0);" size="4">What the
corporate world does.<br>
</font></b></p>
<blockquote>
<p><cite>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. [...]</cite></p>
<p><cite><br>
</cite></p>
</blockquote>
<p><b><font style="color: rgb(0, 0, 0);" size="4">What is
the tendency in free software communities. <cite><br>
</cite></font></b></p>
<blockquote>
<p><cite>[..] 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"? [..] <u>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.</u></cite></p>
</blockquote>
</div>
<div text="#000000" bgcolor="#FFFFFF">
<blockquote> </blockquote>
<pre style="font-family: monospace;" cols="72">--
<a moz-do-not-send="true" href="http://mamot.fr/@drgeo" target="_blank" style="font-family: monospace;">http://mamot.fr/@drgeo</a></pre>
</div>
-- <br>
Cuis-dev mailing list<br>
<a moz-do-not-send="true"
href="mailto:Cuis-dev@lists.cuis.st" target="_blank">Cuis-dev@lists.cuis.st</a><br>
<a moz-do-not-send="true"
href="https://lists.cuis.st/mailman/listinfo/cuis-dev"
rel="noreferrer" target="_blank">https://lists.cuis.st/mailman/listinfo/cuis-dev</a><br>
</blockquote>
</div>
</div>
</blockquote>
<br>
<br>
<pre class="moz-signature" cols="72">--
Juan Vuletich
cuis.st
github.com/jvuletich
researchgate.net/profile/Juan-Vuletich
independent.academia.edu/JuanVuletich
patents.justia.com/inventor/juan-manuel-vuletich
linkedin.com/in/juan-vuletich-75611b3
twitter.com/JuanVuletich</pre>
</body>
</html>