.. _howto-docs:

############################################
How to contribute to the NumPy documentation
############################################

The *Documentation* for a software project is the set of reference,
instructional, educational, informative material generated by the project
developers and contributors, as well as discussions, presentations, videos and
other user-generated content. It may include learning-oriented content (such as
tutorials and how-tos), use-cases or in-depth explanations and reference for
developers.

If you're reading this page, you probably want to help. This guide is meant to
help you decide which kind of content you'll write, as well as give you some
tips and instructions for submitting it to the official NumPy documentation
(that is, the documentation that ships with NumPy and lives on the
:ref:`official project pages <numpy_docs_mainpage>`). Keep in mind that if you
don't want to do this, writing a tutorial on your own blog, creating a YouTube
video or answering questions on social media or Stack Overflow are also great
contributions!

NumPy has a Documentation Team. We have open meetings on Zoom every three weeks
and invite everyone to join. Don't hesitate to reach out if you have questions
or just need someone to guide you through your first steps - we're always happy
to help. Meetings are usually announced on the `numpy-discussion mailing list
<https://mail.python.org/mailman/listinfo/numpy-discussion>`__. Meeting minutes
are taken `on hackmd.io <https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg>`__ and stored
in the `NumPy Archive repository <https://github.com/numpy/archive>`__.

You can find larger planned and in-progress documentation improvement ideas `at
our GitHub project <https://github.com/orgs/numpy/projects/2>`__.

Current vision for the documentation: NEP 44
--------------------------------------------

Recently, the NumPy community approved a *NumPy Enhancement Proposal (NEP)*
about documentation, `NEP 44 - Restructuring the NumPy Documentation
<https://www.numpy.org/neps/nep-0044-restructuring-numpy-docs>`__.

**Where is the documentation?**

The main page for the :ref:`NumPy Documentation <numpy_docs_mainpage>` lists
several categories. The documents mentioned there live in different places.

- **Tutorials, How-Tos, Explanations:** These documents are stored in the NumPy
  source code tree, which means that in order to add them to the official
  documentation, you have to download the NumPy source code,
  :ref:`build it <howto-build-docs>` and submit your changes via a
  :ref:`GitHub pull request <devindex>`.

- **API Reference:** These are mainly the result of rendering the NumPy code
  `docstrings <https://www.python.org/dev/peps/pep-0257/>`__ into formatted
  documents. They are automatically generated when the NumPy documentation is
  :ref:`built from source<howto-build-docs>`.

**Datasets**

If you are writing a tutorial or how-to, we encourage you to use real images and
data (provided they are appropriately licensed and available). This makes the
material more engaging for readers, and choosing the right data can add
pedagogical value to your content.

*Note: currently we cannot easily use data in other packages (except, e.g., from
SciPy or Matplotlib). We plan to create a dedicated datasets package, but that's
not ready yet - please discuss with us if you have data sources in mind.*

Creating new content
--------------------

The documentation is written in restructuredText, which is the format required
by Sphinx, the tool most Python projects use to automatically build and link the
documentation within the project. You can read the
`Quick reStructuredText Guide
<https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__ or the
`reStructuredText Primer
<http://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html>`__ for
more information.

If you have already decided which type of document you want to write, you can
check out the following specific guides:

- Guide to writing Tutorials (TODO)
- :ref:`Guide to writing reference (API) documentation: the numpydoc docstring
  guide <howto-document>`

Major additions to the documentation (e.g. new tutorials) should be proposed to
the `mailing list
<https://mail.python.org/mailman/listinfo/numpy-discussion>`__.
  
Other ways to contribute
------------------------

Correcting technical inaccuracies in the documentation are high priority. For
example, if a docstring is missing a parameter or the description of a
fuction/parameter/method etc. is incorrect. Other "structural" defects like
broken links are also high priority.

Proposals for changes that improve the clarity of the documentation are welcome.
However, "clarity" is a bit subjective, so such proposals are best made by
raising issues that describe what could be improved in the current
documentation. Proposals that include specific suggestions for the improvement
are encouraged as the proposed changes helps frame the discussion.

Based on the above characterization, "high-priority" changes (i.e. fixing
technical inaccuracies, broken links, etc.) can be proposed via pull requests
directly as they are straightforward to review. Other changes should be raised
as issues first so that the discussion can happen before you make major
modifications, which in principle saves you from wasting your time on
undesired changes.

If you see a good tutorial, how-to or explanation that is not included in the
official documentation, you can suggest it to be added by `opening an issue on
GitHub <https://github.com/numpy/numpy/issues>`__. Similarly, opening issues to
suggest a tutorial, how-to or explanation that you can't find anywhere is a
great way to help the documentation team direct efforts towards what users are
looking for. `See this issue <https://github.com/numpy/numpy/issues/15760>`__
for an example of how to do this.

Finally, if you detect a typo or an error in the documentation, or would like to
suggest a different approach, you can also open an issue or submit a pull
request with your suggestion. Keep in mind that changes fixing
grammatical/spelling errors are welcome but not necessarily the highest
priority. "Grammatical correctness" often gets confused with "style" which can
result in unfruitful discussions that don't necessarily improve anything.
Changes that modify wording or rearrange phrasing without changing the technical
content are discouraged. If you think that a different wording improves clarity,
you should open an issue as noted above, but again, changes along these lines
very often tend to be highly subjective and not necessarily do much to improve
the quality of the documentation.

**Final tips**

- Don't worry if English is not your first language. Do your best - we'll revise
  your content and make sure we fix any issues with the code or text.
- If you are unsure whether your tutorial is useful to the community, consider
  submitting an issue on GitHub suggesting it, or asking on the mailing
  list or Stack Overflow.
- If you are unfamiliar with git/GitHub or the process of submitting a pull
  request (PR), check our :ref:`Contributor Guide <devindex>`.

**Other interesting material**

- `writethedocs.org <https://www.writethedocs.org/>`__ has a lot of interesting
  resources for technical writing.
- Google offers two free `Technical Writing Courses
  <https://developers.google.com/tech-writing>`__
- `Software Carpentry <https://software-carpentry.org/software>`__ has a lot of
  nice recommendations for creating educational material.
