This guide will help you decide what to contribute and how to submit it to the official NumPy documentation.
The NumPy community has set a firm goal of improving its documentation. We hold regular documentation meetings on Zoom (dates are announced on the numpy-discussion mailing list), and everyone is welcome. Reach out if you have questions or need someone to guide you through your first steps – we’re happy to help. Minutes are taken on hackmd.io and stored in the NumPy Archive repository.
NumPy docs have the details covered. API reference documentation is generated directly from docstrings in the code when the documentation is built.
What we lack are docs with broader scope – tutorials, how-tos, and explanations. Reporting defects is another way to contribute. We discuss both.
We’re eager to hear about and fix doc defects. But to attack the biggest problems we end up having to defer or overlook some bug reports. Here are the best defects to go after.
Top priority goes to technical inaccuracies – a docstring missing a parameter, a faulty description of a function/parameter/method, and so on. Other “structural” defects like broken links also get priority. All these fixes are easy to confirm and put in place. You can submit a pull request (PR) with the fix, if you know how to do that; otherwise please open an issue.
Typos and misspellings fall on a lower rung; we welcome hearing about them but may not be able to fix them promptly. These too can be handled as pull requests or issues.
Obvious wording mistakes (like leaving out a “not”) fall into the typo category, but other rewordings – even for grammar – require a judgment call, which raises the bar. Test the waters by first presenting the fix as an issue.
Your frustrations using our documents are our best guide to what needs fixing.
If you write a missing doc you join the front line of open source, but it’s a meaningful contribution just to let us know what’s missing. If you want to compose a doc, run your thoughts by the mailing list for futher ideas and feedback. If you want to alert us to a gap, open an issue. See this issue for an example.
If you’re looking for subjects, our formal roadmap for documentation is a NumPy Enhancement Proposal (NEP), NEP 44 - Restructuring the NumPy Documentation. It identifies areas where our docs need help and lists several additions we’d like to see, including Jupyter notebooks.
You can find larger planned and in-progress ideas at our GitHub project.
There are formulas for writing useful documents, and four formulas cover nearly everything. There are four formulas because there are four categories of document – tutorial, how-to guide, explanation, and reference. The insight that docs divide up this way belongs to Daniele Procida, who goes on in this short article to explain the differences and reveal the formulas. When you begin a document or propose one, have in mind which of these types it will be.
tutorial
how-to guide
explanation
reference
Don’t worry if English is not your first language, or if you can only come up with a rough draft. Open source is a community effort. Do your best – we’ll help fix issues.
Images and real-life data make text more engaging and powerful, but be sure what you use is appropriately licensed and available. Here again, even a rough idea for artwork can be polished by others.
For now, the only data formats accepted by NumPy are those also used by other Python scientific libraries like pandas, SciPy, or Matplotlib. We’re developing a package to accept more formats; contact us for details.
NumPy documentation is kept in the source code tree. To get your document into the docbase you must download the tree, build it, and submit a pull request. If GitHub and pull requests are new to you, check our Contributor Guide.
Our markup language is reStructuredText (rST), which is more elaborate than Markdown. Sphinx, the tool many Python projects use to build and link project documentation, converts the rST into HTML and other formats. For more on rST, see the Quick reStructuredText Guide or the reStructuredText Primer
If you run across outside material that would be a useful addition to the NumPy docs, let us know by opening an issue.
You don’t have to contribute here to contribute to NumPy. You’ve contributed if you write a tutorial on your blog, create a YouTube video, or answer questions on Stack Overflow and other sites.
The leading organization of technical writers, Write the Docs, holds conferences, hosts learning resources, and runs a Slack channel.
“Every engineer is also a writer,” says Google’s collection of technical writing resources, which includes free online courses for developers in planning and writing documents.
Software Carpentry’s mission is teaching software to researchers. In addition to hosting the curriculum, the website explains how to present ideas effectively.