[5.0.x] Restructured writing documentation contributing guide.

This trims and clearly delineates the how to guide from the subsequent
explanation with additional subheadings.

These changes have been discussed with Daniele Procida
at the DjangoCon US 2023 sprints.

Backport of a680ac7d775ba1bdbbda03094a4a64596864421c from main

docs/internals/contributing/writing-documentation.txt

@@ -18,26 +18,21 @@ Documentation changes generally come in two forms:
 This section explains how writers can craft their documentation changes
 in the most useful and least error-prone ways.
 
-Getting the raw documentation
-=============================
+The Django documentation process
+================================
 
 Though Django's documentation is intended to be read as HTML at
-https://docs.djangoproject.com/, we edit it as a collection of text files for
-maximum flexibility. These files live in the top-level :source:`docs/` directory of a
-Django release.
+https://docs.djangoproject.com/, we edit it as a collection of plain text files
+written in the reStructuredText markup language for maximum flexibility.
 
-If you'd like to start contributing to our docs, get the development version of
-Django from the source code repository
-(see :ref:`installing-development-version`). The development version has the
+We work from the development version of the repository because it has the
 latest-and-greatest documentation, just as it has the latest-and-greatest code.
+
 We also backport documentation fixes and improvements, at the discretion of the
-merger, to the last release branch. That's because it's highly advantageous to
+merger, to the last release branch. This is because it's advantageous to
 have the docs for the last release be up-to-date and correct (see
 :ref:`differences-between-doc-versions`).
 
-Getting started with Sphinx
-===========================
-
 Django's documentation uses the Sphinx__ documentation system, which in turn
 is based on docutils__. The basic idea is that lightly-formatted plain-text
 documentation is transformed into HTML, PDF, and any other output format.
@@ -45,26 +40,10 @@ documentation is transformed into HTML, PDF, and any other output format.
 __ https://www.sphinx-doc.org/
 __ https://docutils.sourceforge.io/
 
-To build the documentation locally, install Sphinx:
-
-.. console::
-
-     $ python -m pip install Sphinx
-
-Then from the ``docs`` directory, build the HTML:
-
-.. console::
-
-     $ make html
-
-To get started contributing, you'll want to read the :ref:`reStructuredText
-reference <sphinx:rst-index>`.
-
-Your locally-built documentation will be accessible at
-``docs/_build/html/index.html`` and it can be viewed in any web browser, though
-it will be themed differently than the documentation at
-`docs.djangoproject.com <https://docs.djangoproject.com/>`_. This is OK! If
-your changes look good on your local machine, they'll look good on the website.
+Sphinx includes a ``sphinx-build`` command for turning reStructuredText into
+other formats, e.g., HTML and PDF. This command is configurable, but the Django
+documentation includes a ``Makefile`` that provides a shorter ``make html``
+command.
 
 How the documentation is organized
 ==================================
@@ -117,6 +96,104 @@ The documentation is organized into several categories:
   hesitate to refer the reader back to the appropriate tutorial rather than
   repeat the same material.
 
+How to start contributing documentation
+=======================================
+
+Clone the Django repository to your local machine
+-------------------------------------------------
+
+If you'd like to start contributing to our docs, get the development version of
+Django from the source code repository (see
+:ref:`installing-development-version`):
+
+.. console::
+
+     $ git clone https://github.com/django/django.git
+
+If you're planning to submit these changes, you might find it useful to make a
+fork of the Django repository and clone this fork instead.
+
+Set up a virtual environment and install dependencies
+-----------------------------------------------------
+
+Create and activate a virtual environment, then install the dependencies:
+
+.. code-block:: shell
+
+     $ python -m venv .venv
+     $ source .venv/bin/activate
+     $ python -m pip install -r docs/requirements.txt
+
+Build the documentation locally
+-------------------------------
+
+We can build HTML output from the ``docs`` directory:
+
+.. console::
+
+     $ cd docs
+     $ make html
+
+Your locally-built documentation will be accessible at
+``_build/html/index.html`` and it can be viewed in any web browser, though it
+will be themed differently than the documentation at
+`docs.djangoproject.com <https://docs.djangoproject.com/>`_. This is OK! If
+your changes look good on your local machine, they'll look good on the website.
+
+Making edits to the documentation
+---------------------------------
+
+The source files are ``.txt`` files located in the ``docs/`` directory.
+
+These files are written in the reStructuredText markup language. To learn the
+markup, see the :ref:`reStructuredText reference <sphinx:rst-index>`.
+
+To edit this page, for example, we would edit the file
+:source:`docs/internals/contributing/writing-documentation.txt` and rebuild the
+HTML with ``make html``.
+
+.. _documentation-spelling-check:
+
+Spelling check
+--------------
+
+Before you commit your docs, it's a good idea to run the spelling checker.
+You'll need to install :pypi:`sphinxcontrib-spelling` first. Then from the
+``docs`` directory, run ``make spelling``. Wrong words (if any) along with the
+file and line number where they occur will be saved to
+``_build/spelling/output.txt``.
+
+If you encounter false-positives (error output that actually is correct), do
+one of the following:
+
+* Surround inline code or brand/technology names with double grave accents
+  (``).
+* Find synonyms that the spell checker recognizes.
+* If, and only if, you are sure the word you are using is correct - add it
+  to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
+
+.. _documentation-link-check:
+
+Link check
+----------
+
+Links in documentation can become broken or changed such that they are no
+longer the canonical link. Sphinx provides a builder that can check whether the
+links in the documentation are working. From the ``docs`` directory, run ``make
+linkcheck``. Output is printed to the terminal, but can also be found in
+``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``.
+
+Entries that have a status of "working" are fine, those that are "unchecked" or
+"ignored" have been skipped because they either cannot be checked or have
+matched ignore rules in the configuration.
+
+Entries that have a status of "broken" need to be fixed. Those that have a
+status of "redirected" may need to be updated to point to the canonical
+location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
+cases, we do not want to update a "redirected" link, e.g. a rewrite to always
+point to the latest or stable version of the documentation, e.g. ``/en/stable/`` →
+``/en/3.2/``.
+
 Writing style
 =============
 
@@ -529,48 +606,6 @@ example:
 
 That's basically how everything fits together.
 
-.. _documentation-spelling-check:
-
-Spelling check
-==============
-
-Before you commit your docs, it's a good idea to run the spelling checker.
-You'll need to install :pypi:`sphinxcontrib-spelling` first. Then from the
-``docs`` directory, run ``make spelling``. Wrong words (if any) along with the
-file and line number where they occur will be saved to
-``_build/spelling/output.txt``.
-
-If you encounter false-positives (error output that actually is correct), do
-one of the following:
-
-* Surround inline code or brand/technology names with double grave accents
-  (``).
-* Find synonyms that the spell checker recognizes.
-* If, and only if, you are sure the word you are using is correct - add it
-  to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
-
-.. _documentation-link-check:
-
-Link check
-==========
-
-Links in documentation can become broken or changed such that they are no
-longer the canonical link. Sphinx provides a builder that can check whether the
-links in the documentation are working. From the ``docs`` directory, run ``make
-linkcheck``. Output is printed to the terminal, but can also be found in
-``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``.
-
-Entries that have a status of "working" are fine, those that are "unchecked" or
-"ignored" have been skipped because they either cannot be checked or have
-matched ignore rules in the configuration.
-
-Entries that have a status of "broken" need to be fixed. Those that have a
-status of "redirected" may need to be updated to point to the canonical
-location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
-cases, we do not want to update a "redirected" link, e.g. a rewrite to always
-point to the latest or stable version of the documentation, e.g. ``/en/stable/`` →
-``/en/3.2/``.
-
 Translating documentation
 =========================