[Cuis-dev] On the importance of documentation

[Juan Vuletich]

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

Finding ways to encourage people to write documentation is good. Dr Cuis 
is a great take on this.

> *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. [...]
>

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.

> *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._
>

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.

> -- 
> http://mamot.fr/@drgeo

Thanks,

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cuis.st/mailman/archives/cuis-dev/attachments/20250519/94156df1/attachment.htm>