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 official project pages). 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. Meeting minutes are taken on hackmd.io and stored in the NumPy Archive repository.

You can find larger planned and in-progress documentation improvement ideas at our GitHub project.

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.

Where is the documentation?

The main page for the NumPy Documentation 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, build it and submit your changes via a GitHub pull request.

• API Reference: These are mainly the result of rendering the NumPy code docstrings into formatted documents. They are automatically generated when the NumPy documentation is built from source.

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 or the reStructuredText Primer 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)

• Guide to writing reference (API) documentation: the numpydoc docstring guide

Major additions to the documentation (e.g. new tutorials) should be proposed to the mailing list.

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. 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 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 Contributor Guide.

Other interesting material

• writethedocs.org has a lot of interesting resources for technical writing.

• Google offers two free Technical Writing Courses

• Software Carpentry has a lot of nice recommendations for creating educational material.