[Cuis-dev] On the importance of documentation

[Luciano Notarfrancesco]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20250512/01ba243d/attachment.htm>