PROTON-1690: update the readme a bit, add a link to JMH and also outline the modules optional status and how to enable it in the overall build
diff --git a/tests/performance-jmh/README.md b/tests/performance-jmh/README.md
index 02d13f0..be9909a 100644
--- a/tests/performance-jmh/README.md
+++ b/tests/performance-jmh/README.md
@@ -1,13 +1,22 @@
-Proton-J Benchmarks
+Proton-J JMH Benchmarks
-------
-This project contains performance tests designed to stress performance critical parts of the proton engine
-(eg encoders, decoders).
+This module contains optional [JMH](http://openjdk.java.net/projects/code-tools/jmh/) performance tests designed
+to stress performance critical parts of the proton engine (eg encoders, decoders).
+
+Note that this module is an optional part of the overall project build and does not deploy anything, due to its use
+of JMH which is not permissively licensed. The module must either be built directly, or enabled
+within the overall build by using the 'performance-jmh' maven profile.
Building the benchmarks
-------
The benchmarks are maven built and involve some code generation for the JMH part. As such it is required that you
-run 'mvn clean install' on changing the code. As the codebase is rather small it is recommended that you run this
-command from the parent folder to avoid missed changes from other packages.
+rebuild upon changing the code. As the codebase is small it is recommended that you do this from the project
+root folder to avoid missing any changes from other modules.
+
+As noted above this module is optional in the main build, enabled by the performance-jmh profile, so to enable it
+a command such as the following can be used from the root folder:
+
+ mvn clean install -Pperformance-jmh
Running the benchmarks: General
-------
@@ -28,16 +37,16 @@
Some JMH help:
java -jar target/proton-j-performance-jmh.jar -h
-
+
Example
-----
To run a benchmark on the String decoding while saving the results in json format:
java -jar target/proton-j-performance-jmh.jar StringsBenchmark.decode* -f 1 -wi 5 -i 5 -rf json -rff strings_decode_before.json -gc true
-
-After changed something in the String decode path and compiled the whole project, can be taken
-another snapshot of the current state of performances for the same case:
- java -jar target/proton-j-performance-jmh.jar StringsBenchmark.decode* -f 1 -wi 5 -i 5 -rf json -rff strings_decode_after.json -gc true
+After changing something in the String decode path and building the whole project again,
+another snapshot of the current state of performance for the same case can be taken:
+
+ java -jar target/proton-j-performance-jmh.jar StringsBenchmark.decode* -f 1 -wi 5 -i 5 -rf json -rff strings_decode_after.json -gc true
then it is possible to use many graphical tools to compare the results: one is [JMH Visualizer](http://jmh.morethan.io/).
