suggest Docker first, require Python 3.10, reorg

Author: pdurbin

doc/sphinx-guides/source/contributor/documentation.md

@@ -50,76 +50,77 @@ If you would like to read more about the Dataverse's use of GitHub, please see t
 
 ## Building the Guides with Sphinx
 
-While the "quick fix" technique shown above should work fine for minor changes, especially for larger changes, we recommend installing Sphinx on your computer or using a Sphinx Docker container to build the guides locally so you can get an accurate preview of your changes.
+While the "quick fix" technique shown above should work fine for minor changes, in many cases, you're going to want to preview changes locally before committing them.
 
-In case you decide to use a Sphinx Docker container to build the guides, you can skip the next two installation sections, but you will need to have Docker installed.
+Before we worry about pushing changes to the code, let's make sure we can build the guides.
 
-### Installing Sphinx
+Go to <https://github.com/IQSS/dataverse> and click "Code" and then follow the instructions to clone the code locally.
 
-First, make a fork of <https://github.com/IQSS/dataverse> and clone your fork locally. Then change to the ``doc/sphinx-guides`` directory.
+### Makefile and Docker
 
-``cd doc/sphinx-guides``
+From a terminal, switch to the "dataverse" directory you just cloned.
 
-Create a Python virtual environment, activate it, then install dependencies:
-
-``python3 -m venv venv``
+`cd dataverse`
 
-``source venv/bin/activate``
+Then try building the HTML version of the guides.
 
-``pip install -r requirements.txt``
+`make docs-html`
 
-### Installing GraphViz
+If all goes well, you should be able open `doc/sphinx-guides/build/html/index.html` to see the guides you just built.
 
-In some parts of the documentation, graphs are rendered as images using the Sphinx GraphViz extension.
+Here is the complete list of commands.
 
-Building the guides requires the ``dot`` executable from GraphViz.
+- `make docs-html`
+- `make docs-pdf`
+- `make docs-epub`
+- `make docs-all`
 
-This requires having [GraphViz](https://graphviz.org) installed and either having ``dot`` on the path or
-[adding options to the `make` call](https://groups.google.com/forum/#!topic/sphinx-users/yXgNey_0M3I).
+### Docker
 
-On a Mac we recommend installing GraphViz through [Homebrew](<https://brew.sh>). Once you have Homebrew installed and configured to work with your shell, you can type `brew install graphviz`.
+Also from the "dataverse" directory (the root of the git repo), you can try this command:
 
-### Editing and Building the Guides
+`docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:7.2.6 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make html"`
 
-To edit the existing documentation:
+### Sphinx Installed Locally
 
-- Create a branch (see {ref}`how-to-make-a-pull-request`).
-- In ``doc/sphinx-guides/source`` you will find the .rst files that correspond to https://guides.dataverse.org.
-- Using your preferred text editor, open and edit the necessary files, or create new ones.
+First, run `python --version` or `python3 --version` to determine the version of Python you have. If you don't have Python 3.10 or higher, you must upgrade.
 
-Once you are done, you can preview the changes by building the guides locally. As explained, you can build the guides with Sphinx locally installed, or with a Docker container.
+Next, change to the `doc/sphinx-guides` directory.
 
-#### Building the Guides with Sphinx Installed Locally
+`cd doc/sphinx-guides`
 
-Open a terminal, change directories to `doc/sphinx-guides`, activate (or reactivate) your Python virtual environment, and build the guides.
+Create a Python virtual environment, activate it, then install dependencies:
 
-`cd doc/sphinx-guides`
+`python3 -m venv venv`
 
 `source venv/bin/activate`
 
-`make clean`
+`pip install -r requirements.txt`
 
-`make html`
+Next, install [GraphViz](https://graphviz.org) because building the guides requires having the `dot` executable from GraphViz either on the path or passed [as an argument](https://groups.google.com/g/sphinx-users/c/yXgNey_0M3I/m/3T2NipFlBgAJ).
 
-#### Building the Guides with a Sphinx Docker Container and a Makefile
+On a Mac we recommend installing GraphViz through [Homebrew](<https://brew.sh>). Once you have Homebrew installed and configured to work with your shell, you can type `brew install graphviz`.
 
-We have added a Makefile to simplify the process of building the guides using a Docker container, you can use the following commands from the repository root:
+Finally, you can try building the guides with the following command.
 
-- `make docs-html`
-- `make docs-pdf`
-- `make docs-epub`
-- `make docs-all`
+`make html`
 
-#### Building the Guides with a Sphinx Docker Container and CLI
+If all goes well, you should be able open `doc/sphinx-guides/build/html/index.html` to see the guides you just built.
 
-If you want to build the guides using a Docker container, execute the following command in the repository root:
+## Editing, Building, and Previewing the Guides
 
-`docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:7.2.6 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make html"`
+To edit the existing documentation:
+
+- Create a branch (see {ref}`how-to-make-a-pull-request`).
+- In `doc/sphinx-guides/source` you will find the .rst or .md files that correspond to https://guides.dataverse.org.
+- Using your preferred text editor, open and edit the necessary files, or create new ones.
 
-#### Previewing the Guides
+Once you are done, you can preview the changes by building the guides using one of the options above.
 
 After Sphinx is done processing the files you should notice that the `html` folder in `doc/sphinx-guides/build` directory has been updated. You can click on the files in the `html` folder to preview the changes.
 
+## Making a Pull Request
+
 Now you can make a commit with the changes to your own fork in GitHub and submit a pull request. See {ref}`how-to-make-a-pull-request`.
 
 ## Writing Guidelines