<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 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-width:1px;border-left-style:solid;padding-left:1ex;border-left-color:rgb(204,204,204)"><u></u>
<div text="#000000" bgcolor="#FFFFFF">
<p><font size="4" style="color:rgb(0,0,0)">Some interesting reflections on documentation in
the NumPy community:<br>
</font></p>
<p><font size="4" style="color:rgb(0,0,0)"><a 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 size="4" style="color:rgb(0,0,0)">The text is a bit long, so I pasted below some
interesting extracts.</font></p>
<p><b><font size="4" style="color:rgb(0,0,0)">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 size="4" style="color:rgb(0,0,0)"><br>
</font></p>
<p><b><font size="4" style="color:rgb(0,0,0)">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 size="4" style="color:rgb(0,0,0)">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 cols="72" style="font-family:monospace">--
<a 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 href="mailto:Cuis-dev@lists.cuis.st" target="_blank">Cuis-dev@lists.cuis.st</a><br>
<a 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>