8 files changed, 216 insertions, 32 deletions
diff --git a/doc/source/dev/conduct/code_of_conduct.rst b/doc/source/dev/conduct/code_of_conduct.rst
index aca39d8a7..f2f0a536d 100644
--- a/doc/source/dev/conduct/code_of_conduct.rst
+++ b/doc/source/dev/conduct/code_of_conduct.rst
@@ -113,8 +113,8 @@ You can report issues to the NumPy Code of Conduct committee, at
 numpy-conduct@googlegroups.com. Currently, the committee consists of:
 
 - Stefan van der Walt
-- Nathaniel J. Smith
-- Ralf Gommers
+- Melissa Weber Mendonça
+- Anirudh Subramanian
 
 If your report involves any members of the committee, or if they feel they have
 a conflict of interest in handling it, then they will recuse themselves from
diff --git a/doc/source/dev/development_environment.rst b/doc/source/dev/development_environment.rst
index 1f404d6e0..ff78cecc5 100644
--- a/doc/source/dev/development_environment.rst
+++ b/doc/source/dev/development_environment.rst
@@ -211,10 +211,20 @@ Debugging
 ---------
 
 Another frequently asked question is "How do I debug C code inside NumPy?".
-The easiest way to do this is to first write a Python script that invokes the C
-code whose execution you want to debug. For instance ``mytest.py``::
+First, ensure that you have gdb installed on your system with the Python
+extensions (often the default on Linux). You can see which version of
+Python is running inside gdb to verify your setup::
 
-    from numpy import linspace
+    (gdb) python
+    >import sys
+    >print(sys.version_info)
+    >end
+    sys.version_info(major=3, minor=7, micro=0, releaselevel='final', serial=0)
+
+Next you need to write a Python script that invokes the C code whose execution
+you want to debug. For instance ``mytest.py``::
+
+    import numpy as np
     x = np.arange(5)
     np.empty_like(x)
 
@@ -228,10 +238,14 @@ And then in the debugger::
     (gdb) run
 
 The execution will now stop at the corresponding C function and you can step
-through it as usual.  With the Python extensions for gdb installed (often the
-default on Linux), a number of useful Python-specific commands are available.
+through it as usual. A number of useful Python-specific commands are available.
 For example to see where in the Python code you are, use ``py-list``.  For more
-details, see `DebuggingWithGdb`_.
+details, see `DebuggingWithGdb`_. Here are some commonly used commands:
+
+   - ``list``: List specified function or line.
+   - ``next``: Step program, proceeding through subroutine calls.
+   - ``step``: Continue program being debugged, after signal or breakpoint.
+   - ``print``: Print value of expression EXP.
 
 Instead of plain ``gdb`` you can of course use your favourite
 alternative debugger; run it on the python binary with arguments
diff --git a/doc/source/dev/development_workflow.rst b/doc/source/dev/development_workflow.rst
index 9f2ecede6..d5a49a9f9 100644
--- a/doc/source/dev/development_workflow.rst
+++ b/doc/source/dev/development_workflow.rst
@@ -26,7 +26,7 @@ In short:
    - *Contributors*: push your feature branch to your own Github repo, and
      :ref:`create a pull request <asking-for-merging>`.
 
-   - *Core developers* If you want to push changes without
+   - *Core developers*: If you want to push changes without
      further review, see the notes :ref:`below <pushing-to-main>`.
 
 This way of working helps to keep work well organized and the history
@@ -377,10 +377,10 @@ Deleting a branch on github_
    # delete branch locally
    git branch -D my-unwanted-branch
    # delete branch on github
-   git push origin :my-unwanted-branch
+   git push origin --delete my-unwanted-branch
 
-(Note the colon ``:`` before ``test-branch``.  See also:
-https://github.com/guides/remove-a-remote-branch
+See also:
+https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely
 
 
 Several people sharing a single repository
@@ -477,7 +477,7 @@ backport.
 Pushing changes to the main repo
 ================================
 
-*This is only relevant if you have commit rights to the main NumPy repo.*
+*Requires commit rights to the main NumPy repo.*
 
 When you have a set of "ready" changes in a feature branch ready for
 NumPy's ``master`` or ``maintenance`` branches, you can push
diff --git a/doc/source/dev/gitwash/git_links.inc b/doc/source/dev/gitwash/git_links.inc
index f69a3cf62..82e6c75e5 100644
--- a/doc/source/dev/gitwash/git_links.inc
+++ b/doc/source/dev/gitwash/git_links.inc
@@ -2,7 +2,7 @@
    and name substitutions.  It may be included in many files,
    therefore it should only contain link targets and name
    substitutions.  Try grepping for "^\.\. _" to find plausible
-   candidates for this list.  
+   candidates for this list.
 
 .. NOTE: reST targets are
    __not_case_sensitive__, so only one target definition is needed for
@@ -18,7 +18,7 @@
 .. _pro git book: https://git-scm.com/book/
 .. _git svn crash course: https://git-scm.com/course/svn.html
 .. _learn.github: https://learn.github.com/
-.. _network graph visualizer: https://github.com/blog/39-say-hello-to-the-network-graph-visualizer
+.. _network graph visualizer: https://github.blog/2008-04-10-say-hello-to-the-network-graph-visualizer/
 .. _git user manual: https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
 .. _git tutorial: https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
 .. _git community book: https://book.git-scm.com/
@@ -41,18 +41,18 @@
 .. _git config: https://www.kernel.org/pub/software/scm/git/docs/git-config.html
 .. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
 .. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
-.. _tangled working copy problem: https://tomayko.com/writings/the-thing-about-git 
+.. _tangled working copy problem: https://tomayko.com/writings/the-thing-about-git
 .. _git management: http://kerneltrap.org/Linux/Git_Management
 .. _linux git workflow: https://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html
-.. _ipython git workflow: http://mail.python.org/pipermail/ipython-dev/2010-October/006746.html
+.. _ipython git workflow: https://mail.python.org/pipermail/ipython-dev/2010-October/005632.html
 .. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html
 .. _git foundation: http://matthew-brett.github.com/pydagogue/foundation.html
 .. _numpy/master: https://github.com/numpy/numpy
 .. _git cherry-pick: https://www.kernel.org/pub/software/scm/git/docs/git-cherry-pick.html
 .. _git blame: https://www.kernel.org/pub/software/scm/git/docs/git-blame.html
-.. _this blog post: https://github.com/blog/612-introducing-github-compare-view 
-.. _this article on merging conflicts:  https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts 
-.. _learn git: https://www.atlassian.com/git/tutorials/
+.. _this blog post: https://github.com/blog/612-introducing-github-compare-view
+.. _this article on merging conflicts:  https://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts
+.. _learn git:  https://try.github.io/
 .. _filing pull requests: https://help.github.com/articles/using-pull-requests/#initiating-the-pull-request
 .. _pull request review: https://help.github.com/articles/using-pull-requests/#reviewing-the-pull-request
 
diff --git a/doc/source/dev/governance/people.rst b/doc/source/dev/governance/people.rst
index 10af7f221..db2704d09 100644
--- a/doc/source/dev/governance/people.rst
+++ b/doc/source/dev/governance/people.rst
@@ -56,7 +56,7 @@ NumFOCUS Subcommittee
 Institutional Partners
 ----------------------
 
-* UC Berkeley (Stefan van der Walt, Matti Picus, Tyler Reddy, Sebastian Berg)
+* UC Berkeley (Stefan van der Walt, Sebastian Berg, Warren Weckesser, Ross Barnowski)
 
-* Quansight (Ralf Gommers, Hameer Abbasi)
+* Quansight (Ralf Gommers, Hameer Abbasi, Melissa Weber Mendonça, Mars Lee, Matti Picus)
 
diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst
new file mode 100644
index 000000000..0e2e03e0b
--- /dev/null
+++ b/doc/source/dev/howto-docs.rst
@@ -0,0 +1,149 @@
+.. _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.
diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst
index 1aacc2c49..5270bfb77 100644
--- a/doc/source/dev/index.rst
+++ b/doc/source/dev/index.rst
@@ -1,3 +1,5 @@
+.. _devindex:
+
 #####################
 Contributing to NumPy
 #####################
@@ -10,24 +12,23 @@ we list them in alphabetical order):
 - Community coordination
 - DevOps
 - Developing educational content & narrative documentation
-- Writing technical documentation
 - Fundraising
-- Project management
 - Marketing
+- Project management
 - Translating content
 - Website design and development
+- Writing technical documentation
 
 The rest of this document discusses working on the NumPy code base and documentation.
 We're in the process of updating our descriptions of other activities and roles.
 If you are interested in these other activities, please contact us!
 You can do this via
-the `numpy-discussion mailing list <https://scipy.org/scipylib/mailing-lists.html>`__,
-or on GitHub (open an issue or comment on a relevant issue). These are our preferred
-communication channels (open source is open by nature!), however if you prefer
-to discuss in private first, please reach out to our community coordinators
-at `numpy-team@googlegroups.com` or `numpy-team.slack.com` (send an email to
-`numpy-team@googlegroups.com` for an invite the first time).
-
+the `numpy-discussion mailing list <https://mail.python.org/mailman/listinfo/numpy-discussion>`__,
+or on `GitHub <https://github.com/numpy/numpy>`__ (open an issue or comment on a
+relevant issue). These are our preferred communication channels (open source is open
+by nature!), however if you prefer to discuss in private first, please reach out to
+our community coordinators at `numpy-team@googlegroups.com` or `numpy-team.slack.com`
+(send an email to `numpy-team@googlegroups.com` for an invite the first time).
 
 Development process - summary
 =============================
@@ -85,7 +86,7 @@ Here's the short summary, complete TOC links are below:
 
    * Enter your GitHub username and password (repeat contributors or advanced
      users can remove this step by connecting to GitHub with
-     :ref:`SSH<set-up-and-configure-a-github-account>` .
+     :ref:`SSH<set-up-and-configure-a-github-account>`).
 
    * Go to GitHub. The new branch will show up with a green Pull Request
      button. Make sure the title and message are clear, concise, and self-
@@ -198,6 +199,13 @@ Pull requests (PRs) that modify code should either have new tests, or modify exi
 tests to fail before the PR and pass afterwards. You should :ref:`run the tests
 <development-environment>` before pushing a PR.
 
+Running NumPy's test suite locally requires some additional packages, such as
+``pytest`` and ``hypothesis``. The additional testing dependencies are listed
+in ``test_requirements.txt`` in the top-level directory, and can conveniently
+be installed with::
+
+    pip install -r test_requirements.txt
+
 Tests for a module should ideally cover all code in that module,
 i.e., statement coverage should be at 100%.
 
@@ -231,6 +239,11 @@ Requirements
 `Sphinx <http://www.sphinx-doc.org/en/stable/>`__ is needed to build
 the documentation. Matplotlib, SciPy, and IPython are also required.
 
+These additional dependencies for building the documentation are listed in
+``doc_requirements.txt`` and can be conveniently installed with::
+
+    pip install -r doc_requirements.txt
+
 The numpy documentation also depends on the
 `numpydoc <https://numpydoc.readthedocs.io/en/latest/>`__ sphinx extension
 as well as an external sphinx theme.
@@ -273,6 +286,7 @@ The rest of the story
    style_guide
    releasing
    governance/index
+   howto-docs
 
 NumPy-specific workflow is in :ref:`numpy-development-workflow
 <development-workflow>`.
diff --git a/doc/source/dev/underthehood.rst b/doc/source/dev/underthehood.rst
new file mode 100644
index 000000000..4dae48689
--- /dev/null
+++ b/doc/source/dev/underthehood.rst
@@ -0,0 +1,7 @@
+.. _underthehood:
+
+===========================================
+Under-the-hood Documentation for developers
+===========================================
+
+To be completed.