[Cuis-dev] On the importance of documentation

[Hilaire Fernandes]

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