finished full first pass

docs/contrib.rst

@@ -322,6 +322,36 @@ add it to either the ``docs/internal_api/index.rst`` or
 ``docs/user_api/index.rst`` file, depending on whether the function is intended
 for internal or external use.
 
+Editing other documentation files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We welcome changes and improvements to all parts of our documentation (including
+this guide)! You can find these files in the ``docs`` directory.
+
+These files are mainly written in `reStructuredText
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__,
+but additional file types such as ``.md`` and ``.ipynb`` are also used.
+
+Important documentation files to know about include:
+
+* ``docs/index.rst``: This file is the main page of the documentation. Files
+  added to ``toctree`` blocks in this file will be included in the documentation
+  as top-level subpages.
+
+* ``docs/contrib.rst``: This file is the source for this guide!
+
+* ``docs/conf.py``: This file contains the configuration for building the documentation.
+
+* ``docs/examples/*.ipynb``, ``docs/examples.rst``, and ``docs/gallery.yml``:
+  These files are used to generate the jupyter notebook examples in the
+  documentation. Notebooks in the ``docs/examples/`` directory are added to the
+  documentation by adding them to the ``toctree`` in ``docs/examples.rst`` and
+  linked to their cover picture by addidng them to the ``docs/gallery.yml``
+  file.
+
+See the `sphinx documentation <https://www.sphinx-doc.org/en/master/>`__ for
+more informatiion about writing sphinx documentation.
+
 
 Generate the documentation locally
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -348,21 +378,68 @@ from your PR and see any warnings or errors on your build.
 Contribute your code
 --------------------
 
-Once you have prepared your changes and are ready for them to be reviewed by the GeoCAT team, you can open a pull request. This section describes how to open a pull request and what to expect after you open it.
+Once you have prepared your changes and are ready for them to be reviewed by the
+GeoCAT team, you can open a pull request. This section describes how to open a
+pull request and what to expect after you open it.
 
+Push your changes to your fork
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once you have made your changes locally, you will need to push them to your
+branch on your fork on GitHub. To do this, use the following command:
+
+.. code-block:: bash
 
+    git push
 
+From here, you can request that your changes be merged into the main repository in the form of a pull request.
 
+Making a pull request
+^^^^^^^^^^^^^^^^^^^^^
+
+GitHub has extensive `pull request guides and documentation
+<https://docs.github.com/en/pull-requests>`__ that we recommend. This section
+describes the basics for our workflow.
+
+From your branch on your fork, open the "Pull requests" tab and click the "New
+pull request" button. Make sure the "base repository" is "NCAR/geocat-comp" and
+the "base" branch is set to "main", wiht the "head repository" and "compare"
+branch set to your fork and prepared branch, respectively.
+
+From this page, you can see a view of the changes you have made in your branch.
+
+We recommend adding a short, descriptive title to your pull request. The body of
+the pull request should autofill with our pull request template, which has it's
+own set of directions. Please fill out the relevant sections of the template,
+including adding a more detailed description of your changes.
+
+Once you have filled out the template, click the "Create pull request" button.
+This will open your pull request on the ``geocat-comp`` repository.
+
+If you want to open a pull request but are not ready for it to be reviewed, you
+can open the pull request as a draft. This is also a good way to get feedback on
+your work that might not be ready to contribute yet.
+
+Addressing feedback
+^^^^^^^^^^^^^^^^^^^
+
+After you open your pull request, the GeoCAT team will review it and
+may provide feedbac like asking for changes or suggesting improvements. You can
+address this feedback by making changes to your branch and pushing them to your
+fork. The pull request will automatically update with your changes.
+
+The GeoCAT team appreciates your contributions and the interactive process of
+reviewing pull requests, and will do our best to review your pull request in a
+timely manner. It is totally normal to have to make several rounds of changes to
+your pull request before it is ready to be merged, especially if you are new to
+the project.
 
-Contibuting to documentation
-----------------------------
+Once your pull request is approved by a core maintainer and passes the relevant
+checks, it will be merged into the main repository!
 
-- where
-- sphinx
-- rst
-- how to build
 
+Delete your branch
+^^^^^^^^^^^^^^^^^^
 
-Opening a pull request
-----------------------
-- pull request template
+We recommend deleting your branch after your pull request is merged. This will
+help keep your fork clean and organized, but is not required.