[Cuis-dev] Re : Re: On the importance of documentation

[H. Fernandes]

I completely agree, I was exactly thinking about that recently.

Such documentation will go as a tutorial documentation. Do you know any such doc.

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