Update dev docs

docs/source/dev/development_environment.rst

@@ -14,9 +14,8 @@ creating a :ref:`virtual environment <virtual-environments>` to isolate the
 development dependencies from your system's python packages.
 
 Once that is set up, simply clone the repository into a directory of your 
-choosing, and after making sure your virtual environment is activated, run::
-
-    $ make install
+choosing, and after making sure your virtual environment is activated, follow
+the instructions for :ref:`building-in-place`.
 
 
 .. _testing-builds:
@@ -39,7 +38,8 @@ repeatedly until no installations remain) and running the following commands
 
     Remember that all tests of Simphony should pass before committing your changes.
 
-Using ``pytest`` is the recommended approach to running tests (see :ref:`running-tests`).
+Using ``pytest`` (through tox) is the recommended approach to running tests 
+(see :ref:`running-tests`).
 
 
 .. _building-in-place:
@@ -50,11 +50,12 @@ Building in-place
 For development, you can set up an in-place build so that changes made to
 ``.py`` files have effect without rebuild. First, run::
 
-    $ pip install -e .
+    $ make install
 
 This allows you to import the in-place built Simphony *from any location the
 Python environment used to install it is activated*. If this is your system
-Python, you will be able to use the Simphony package from any directory.
+Python, you will be able to use the Simphony package from any directory, 
+although installing a development version in your system Python is not recommended.
 
 Now editing a Python source file in Simphony allows you to immediately
 test and use your changes (in ``.py`` files), without even restarting the
@@ -66,9 +67,6 @@ interpreter.
 Using virtual environments
 --------------------------
 
-A frequently asked question is "How do I set up a development version of NumPy
-in parallel to a released version that I use to do my job/research?".
-
 One simple way to set up a development version of Simphony in parallel with a
 regular install is to install the released version in
 site-packages (perhaps using pip) and set

docs/source/dev/development_workflow.rst

@@ -6,12 +6,12 @@ Development workflow
 
 **Prerequisites**:
 You already have your own forked copy of the Simphony_ repository, you have 
-configured git, and have linked the upstream repository.
+configured git, and have `linked the upstream repository`_.
 
 What is described below is a recommended workflow with Git.
 
 .. _Simphony: https://github.com/BYUCamachoLab/simphony
-
+.. _linked the upstream repository: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork
 
 Basic workflow
 ##############
@@ -39,12 +39,10 @@ ensure that a pip installation of your updated package installs and functions
 properly. To test this, try installing your package locally by removing all 
 installed versions of Simphony (by running ```pip3 uninstall simphony``` 
 repeatedly until no installations remain) and running the following commands 
-(from Simphony's toplevel directory):
+(from Simphony's toplevel directory): ::
 
-```
-python3 setup.py sdist bdist_wheel  
-pip3 install dist/simphony-[VERSION].tar.gz
-```
+   $ python3 setup.py sdist bdist_wheel  
+   $ pip3 install dist/simphony-[VERSION].tar.gz
 
 Also be sure to include tests for all the code you add, making certain the tests are
 thorough and always pass.

docs/source/dev/index.rst

@@ -2,15 +2,15 @@
 Contributing to Simphony
 ########################
 
-Not a coder? Not a problem! Simphony is still a developing project, 
+Not a developer? Not a problem! Simphony is still a developing project, 
 and we could use a lot of help.
 These are all activities we'd like to get help with (they're all important, so
 we list them in alphabetical order):
 
 - Code maintenance and development (architecture input welcome)
-- Fundraising
-- Marketing
-- Writing technical documentation and examples
+- Marketing, getting the word out and increasing usage
+- Writing technical documentation and examples (particularly if you're just a 
+  user but have found the project useful)
 
 Development process - summary
 =============================
@@ -69,8 +69,8 @@ Here's the short summary, complete TOC links are below:
      users can remove this step by connecting to GitHub with SSH).
 
    * 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-
-     explanatory. Then click the button to submit it.
+     button. Make sure the title and message are clear, concise, and 
+     self-explanatory. Then click the button to submit it.
 
 4. Review process:
 
@@ -146,8 +146,10 @@ Stylistic Guidelines
 
 * Set up your editor to follow `PEP 8 <https://www.python.org/dev/peps/
   pep-0008/>`_ (remove trailing white space, no tabs, etc.).  Check code with
-  pyflakes / flake8.
-  .. FIXME: Do we want to use `black` instead?
+  flake8, and be aware that a pre-commit hook will run the autoformatter
+  Black_ over all of your committed code.
+
+.. _Black: https://black.readthedocs.io/
 
 
 Test coverage