<!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"> Hi Hilaire, I agree that documentation is important. As important as the software being documented (Cuis in our case). But I don't agree with everything that is said there. Some comments inline. On 5/8/2025 5:59 AM, Hilaire Fernandes via Cuis-dev wrote: <blockquote cite="mid:567aa2cd-dba3-48df-9212-89dc8b4cd360@free.fr" type="cite"> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> Some interesting reflections on documentation in the NumPy community: <a moz-do-not-send="true" class="moz-txt-link-freetext" href="https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community">https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community</a> The text is a bit long, so I pasted below some interesting extracts. Why documentation is important. <blockquote> <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> <cite>So, if everybody agrees on its importance, why is it so hard to write good documentation?</cite> </blockquote> </blockquote> Finding ways to encourage people to write documentation is good. Dr Cuis is a great take on this. <blockquote cite="mid:567aa2cd-dba3-48df-9212-89dc8b4cd360@free.fr" type="cite"> <blockquote> </blockquote> What the corporate world does. <blockquote> <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> </blockquote> </blockquote> This remark makes sense for end user software. Cuis is a development environment aimed at software developers. I think it is fair to assume that software developers need to be able to read technical documentation written by and for other software developers. I don't mind technical writers helping, but not having them is no excuse for not writing decent technical documentation ourselves. <blockquote cite="mid:567aa2cd-dba3-48df-9212-89dc8b4cd360@free.fr" type="cite"> <blockquote><cite></cite> </blockquote> What is the tendency in free software communities. <cite> </cite> <blockquote> <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"? [..] 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.</cite> </blockquote> </blockquote> This is where I disagree. Technical documentation of software in an open source project should be mainly written by the code authors themselves. It is the duty of each contributor of code to also write appropriate documentation. In many cases, that documentation is part of the software itself. Perhaps we'd not accept code without good comments at all. In any case, encouraging everybody to write documentation should not mean asking less experience people to document things they don't understand well. Everybody should be encouraged to write documentation at the level they feel confident at. For instance, a newcomer to Cuis can evaluate our beginner instructions much better than we old timers. And the minute after they understand the solution to some problem is when they are in the best position to write about it. <blockquote cite="mid:567aa2cd-dba3-48df-9212-89dc8b4cd360@free.fr" type="cite"> <blockquote> </blockquote> <pre class="moz-signature" cols="72">-- <a moz-do-not-send="true" class="moz-txt-link-freetext" href="http://mamot.fr/@drgeo">http://mamot.fr/@drgeo</a></pre> </blockquote> Thanks, <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>