Merge pull request #10520 from astrochun/doc_suggestions

Minor updates to documentation for new contributors

CONTRIBUTING.md

@@ -8,8 +8,8 @@ When opening an issue to report a problem, please try to provide a minimal code
 example that reproduces the issue along with details of the operating
 system and the Python, NumPy, and `astropy` versions you are using.
 
-Contributing Code
------------------
+Contributing
+------------
 
 So you are interested in contributing code to the Astropy Project? Excellent!
 We love contributions! Astropy is open source, built on open source,
@@ -41,8 +41,10 @@ Note: This disclaimer was originally written by
 Astropy based on its use in the README file for the
 [MetPy project](https://github.com/Unidata/MetPy).
 
-Most contributions to Astropy are done via pull requests from GitHub users'
-forks of the [astropy repository](https://github.com/astropy/astropy). If you
+### How to Contribute, Best Practices
+
+All contributions to Astropy are done via [pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) from GitHub users'
+"forks" (i.e., copies) of the [astropy repository](https://github.com/astropy/astropy). If you
 are new to this style of development, you will want to read over our
 [development workflow](https://docs.astropy.org/en/latest/development/workflow/development_workflow.html).
 
@@ -76,10 +78,10 @@ include the following:
   performance, consider adding a performance benchmark in the
   [astropy-benchmarks](https://github.com/astropy/astropy-benchmarks)
   repository. You can find out more about how to do this
-  [in the README for that repository](https://github.com/astropy/astropy-benchmarks#contributing-a-benchmark).
+  [in the README for that repository](https://github.com/astropy/astropy-benchmarks#contributing-benchmarks).
 
 - **Changelog entry**: whether you are fixing a bug or adding new
-  functionality, you should add an entry to the ``CHANGES.rst`` file that
+  functionality, you should add an entry to the [``CHANGES.rst``](CHANGES.rst) file that
   includes the PR number. If you are opening a pull request you may not know
   the PR number yet, but you can add it once the pull request is open. If you
   are not sure where to put the changelog entry, wait until a maintainer
@@ -95,9 +97,11 @@ include the following:
 Other Tips
 ----------
 
-- To prevent the automated tests from running, you can add ``[ci skip]`` to your
-  commit message. This is useful if your PR is a work in progress and you are
-  not yet ready for the tests to run. For example:
+- Behind the scenes, we conduct a number of tests or checks with new pull requests.
+  This is a technique that is called continuous integration, and we use Travis CI
+  and CircleCI. To prevent the automated tests from running, you can add ``[ci skip]``
+  to your commit message. This is useful if your PR is a work in progress (WIP) and
+  you are not yet ready for the tests to run. For example:
 
       $ git commit -m "WIP widget [ci skip]"
 

docs/development/vision.rst

@@ -89,8 +89,8 @@ packages being integrated into the core package are consistent with those
 already in the core package.
 
 Initially, no dependency on GUI toolkits will be allowed in the core package.
-If the community reaches agrees on a single toolkit that could be used, then
-this toolkit will be allowed (but will only be imported as needed).
+If the community reaches an agreement on a single toolkit that could be used,
+then this toolkit will be allowed (but will only be imported as needed).
 
 Keeping track of affiliated packages
 ====================================

docs/development/workflow/development_workflow.rst

@@ -31,12 +31,13 @@ development version or stable version is the active one.
 up. It is well worth your time.
 
 Not sure what your first contribution should be? Take a look at the `Astropy
-issue list`_ and grab one labeled "package-novice". These issues are the
-most accessible ones if you are not familiar with the Astropy source
-code. Issues labeled as "effort-low" are expected to take a few hours (at
-most) to address, while the "effort-medium" ones may take a few days. The
-developers are friendly and want you to help, so don't be shy about asking
-questions on the `astropy-dev mailing list`_.
+issue list`_ and grab one labeled `"package-novice" <https://github.com/astropy/astropy/issues?q=is%3Aissue+is%3Aopen+label%3Apackage-novice>`_.
+These issues are the most accessible ones if you are not familiar with the
+Astropy source code. Issues labeled as `"effort-low" <https://github.com/astropy/astropy/issues?q=is%3Aissue+is%3Aopen+label%3Aeffort-low>`_
+are expected to take a few hours (at most) to address, while the
+`"effort-medium" <https://github.com/astropy/astropy/issues?q=is%3Aissue+is%3Aopen+label%3Aeffort-medium>`_
+ones may take a few days. The developers are friendly and want you to help, so
+don't be shy about asking questions on the `astropy-dev mailing list`_.
 
 New to `git`_?
 **************

docs/development/workflow/virtual_pythons.rst

@@ -129,7 +129,13 @@ environment.
       `documentation for the conda command`_ and the
       `guide on how to manage environments`_.
 
-    + If astropy is installed in your environment, you may need to uninstall it
+    + Next activate the environment ``ENV`` with:
+
+        conda activate ENV
+
+    + Your command-line prompt will contain ``ENV`` in parentheses by default.
+
+    + If astropy is installed in your ``ENV`` environment, you may need to uninstall it
       in order for the development version to install properly. You can do this
       with the following command::