DOC: Tighten howto-docs guide #16259 (#16385)

* DOC: rreword much of the howto-docs guide

1 files changed, 136 insertions, 129 deletions

diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
index e8bafd254..17194bd58 100644
--- a/doc/source/dev/howto-docs.rst
+++ b/doc/source/dev/howto-docs.rst
@@ -4,146 +4,153 @@
 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
+This guide will help you decide what to contribute and how to submit it to the
+official NumPy documentation.
+
+******************************************************************************
+Documentation team meetings
+******************************************************************************
+
+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
+<https://mail.python.org/mailman/listinfo/numpy-discussion>`__), 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 <https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg>`__
+and stored in the `NumPy Archive repository
+<https://github.com/numpy/archive>`__.
+
+*************************
+What's needed
+*************************
+NumPy docs have the details covered. API reference
+documentation is generated directly from
+`docstrings <https://www.python.org/dev/peps/pep-0257/>`_ in the code
+when the documentation is :ref:`built<howto-build-docs>`.
+
+What we lack are docs with broader scope -- tutorials, how-tos, and explanations.
+Reporting defects is another way to contribute. We discuss both.
+
+*************************
+Contributing fixes
+*************************
+
+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) <https://numpy.org/devdocs/dev/index.html#devindex>`__
+with the fix, if you know how to do that; otherwise please `open an issue
+<https://github.com/numpy/numpy/issues>`__.
+
+**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.
+
+******************************************************************************
+Contributing new pages
+******************************************************************************
+
+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
+<https://mail.python.org/mailman/listinfo/numpy-discussion>`__ for futher
+ideas and feedback. If you want to alert us to a gap,
+`open an issue <https://github.com/numpy/numpy/issues>`__. See
+`this issue <https://github.com/numpy/numpy/issues/15760>`__ 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 <https://www.numpy.org/neps/nep-0044-restructuring-numpy-docs>`__.
+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 <https://github.com/orgs/numpy/projects/2>`__.
 
-Current vision for the documentation: NEP 44
---------------------------------------------
+.. _tutorials_howtos_explanations:
 
-Recently, the NumPy community approved a *NumPy Enhancement Proposal (NEP)*
-about documentation,
-:ref:`NEP 44 - Restructuring the NumPy Documentation <NEP44>`.
 
-**Where is the documentation?**
+Formula writing
+==============================================================================
+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 <https://documentation.divio.com/>`__ 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.
 
-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>`.
+.. _contributing:
 
-- **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**
+More on contributing
+==============================================================================
 
-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.
+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.
 
-*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.*
+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.
 
-Creating new content
---------------------
+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.
 
-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
+NumPy documentation is kept in the source code tree. To get your document
+into the docbase you must download the tree, :ref:`build it
+<howto-build-docs>`, and submit a pull request. If GitHub and pull requests
+are new to you, check our :ref:`Contributor Guide <devindex>`.
+
+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
 <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://carpentries.github.io/curriculum-development/>`__ has a lot of
-  nice recommendations for creating educational material.
+<http://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html>`__
+
+
+************************************************************
+Contributing indirectly
+************************************************************
+
+If you run across outside material that would be a useful addition to the
+NumPy docs, let us know by `opening an issue <https://github.com/numpy/numpy/issues>`__.
+
+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.
+
+
+************************************************************
+Documentation reading
+************************************************************
+
+- The leading organization of technical writers,
+  `Write the Docs <https://www.writethedocs.org/>`__,
+  holds conferences, hosts learning resources, and runs a Slack channel.
+
+- "Every engineer is also a writer," says Google's
+  `collection of technical writing resources <https://developers.google.com/tech-writing>`__,
+  which includes free online courses for developers in planning and writing
+  documents.
+
+- `Software Carpentry's <https://software-carpentry.org/lessons>`__ mission is
+  teaching software to researchers. In addition to hosting the curriculum, the
+  website explains how to present ideas effectively.