improve benchmark doc

1 files changed, 30 insertions, 4 deletions

diff --git a/benchmarks/README.rst b/benchmarks/README.rst
index b67994ce0..b1bdc00cb 100644
--- a/benchmarks/README.rst
+++ b/benchmarks/README.rst
@@ -16,22 +16,48 @@ unless told otherwise. Some of the benchmarking features in
 ``runtests.py``. To run the benchmarks, you do not need to install a
 development version of NumPy to your current Python environment.
 
-Run a benchmark against currently checked out NumPy version (don't
-record the result)::
+*Before beginning, ensure that* [airspeed velocity](https://github.com/airspeed-velocity/asv) *is installed.* By default, `asv` ships with support for [anaconda](https://store.continuum.io/cshop/anaconda/) and [virtualenv](https://pypi.python.org/pypi/virtualenv).
+
+```
+pip install asv
+pip install virtualenv
+```
+
+After contributing new benchmarks, you should test them locally before submitting a pull request.
+
+To run all benchmarks, navigate to the root NumPy directory at the command line and execute:
+
+```
+python runtests.py --bench
+```
+
+ where `--bench` activates the benchmark suite instead of the test suite. This builds NumPy and runs the benchmarks. 
+
+ To run benchmarks from a particular benchmark module, such as `bench_core.py`, simply append the filename without the extension::
 
     python runtests.py --bench bench_core
 
-Compare change in benchmark results to another version::
+To run a benchmark defined in a class, such as `Mandelbrot` from `bench_avx.py`::
+
+```
+python runtests.py --bench bench_avx.Mandelbrot
+```
+
+Compare change in benchmark results to another version/commit/branch::
 
     python runtests.py --bench-compare v1.6.2 bench_core
+    python runtests.py --bench-compare 8bf4e9b bench_core
+    python runtests.py --bench-compare master bench_core
 
-Run ASV commands (record results and generate HTML)::
+ All of the commands above display the results in plain text in the console, and the results are not saved for comparison with future commits. For greater control, a graphical view, and to have results saved for future comparison you can run ASV commands (record results and generate HTML)::
 
     cd benchmarks
     asv run --skip-existing-commits --steps 10 ALL
     asv publish
     asv preview
 
+ ASV will report that it is running a server. Using any browser, you can review the results by navigating to [http://127.0.0.1:8080](http://127.0.0.1:8080/) (local machine, port 8080). 
+
 More on how to use ``asv`` can be found in `ASV documentation`_
 Command-line help is available as usual via ``asv --help`` and
 ``asv run --help``.