<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p><font size="4">Some interesting reflections on documentation in
the NumPy community:<br>
</font></p>
<p><font size="4"><a 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></font></p>
<p><font size="4">The text is a bit long, so I pasted below some
interesting extracts.</font></p>
<p><b><font size="4">Why documentation is important.<br>
</font></b></p>
<blockquote>
<p><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>
</p>
<p><cite>So, if everybody agrees on its importance, why is it so
hard to write good documentation?</cite></p>
</blockquote>
<p><font size="4"><br>
</font></p>
<p><b><font size="4">What the corporate world does.<br>
</font></b></p>
<blockquote>
<p><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></p>
<p><cite><br>
</cite></p>
</blockquote>
<p><b><font size="4">What is the tendency in free software
communities. <cite><br>
</cite></font></b></p>
<blockquote>
<p><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"? [..] <u>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.</u></cite></p>
</blockquote>
<pre class="moz-signature" cols="72">--
<a class="moz-txt-link-freetext" href="http://mamot.fr/@drgeo">http://mamot.fr/@drgeo</a></pre>
</body>
</html>