diff --git a/README.md b/README.md
index de844ef..6da9f40 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 # solidity-coverage
-
+[![npm version](https://badge.fury.io/js/solidity-coverage.svg)](https://badge.fury.io/js/solidity-coverage)
 [![CircleCI](https://circleci.com/gh/sc-forks/solidity-coverage.svg?style=svg)](https://circleci.com/gh/sc-forks/solidity-coverage)
 [![codecov](https://codecov.io/gh/sc-forks/solidity-coverage/branch/master/graph/badge.svg)](https://codecov.io/gh/sc-forks/solidity-coverage)
 [![Stories in Ready](https://badge.waffle.io/sc-forks/solidity-coverage.png?label=ready&title=Ready)](https://waffle.io/sc-forks/solidity-coverage?utm_source=badge)
@@ -59,24 +59,19 @@ module.exports = {
 
 You can also create a `.solcover.js` config file in the root directory of your project and specify 
 some additional options:
-+ **port**: {Number} The port you want solidity-coverage to run testrpc on / have truffle connect to.
-+ **testrpcOptions**: {String} A string of options to be appended to a command line invocation 
-of testrpc. 
-  + Example: `--account="0x89a...b1f',10000" --port 8777`". 
-  + Note: you should specify the port in your `testrpcOptions` string AND as a `port` option.
-+ **testCommand**: {String} By default solidity-coverage runs `truffle test` or `truffle test --network coverage`. 
-This option lets you run tests some other way: ex: `mocha --timeout 5000`. You 
-will probably also need to make sure the web3 provider for your tests explicitly connects to the port solidity-coverage's 
-testrpc is set to run on, e.g: 
-  + `var web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8555"))`
-+ **norpc**: {Boolean} When true, solidity-coverage will not launch its own testrpc instance. This
-can be useful if you are running tests using a different vm like the 
-[`sc-forks` version of `pyethereum`](https://github.com/sc-forks/pyethereum). (Default: false).  
-+ **dir**: {String} : By default, solidity-coverage looks for a `contracts` folder in your root
++ **port**: *{ Number }* Port to run testrpc on / have truffle connect to. (Default: 8555)
++ **testrpcOptions**: *{ String }* options to append to a command line invocation of testrpc. 
+  + ex: `--secure --unlock "0x1234..." --unlock "0xabcd..."`. 
+  + NB: if you specify the port in your rpc options string, also declare it as a `port` option.
++ **testCommand**: *{ String }* By default solidity-coverage runs `truffle test`. This option lets 
+you run an arbitrary test command instead, like: `mocha --timeout 5000`. 
+  + remember to set the config's port option to whatever port your tests use (probably 8545). 
+  + make sure you don't have another instance of testrpc running on that port (web3 will error if you do). 
++ **norpc**: *{ Boolean }* When true, solidity-coverage will not launch its own testrpc instance. This
+can be useful if you are using a different vm like the [sc-forks version of pyethereum](https://github.com/sc-forks/pyethereum).  
++ **dir**: *{ String }* : Solidity-coverage usually looks for a `contracts` folder in your root
 directory. `dir` allows you to define a relative path from the root directory to the contracts
-folder. A `dir` of `./secretDirectory` would tell solidity-coverage to look for `./secretDirectory/contracts`
-
-
+folder. `dir: "./secretDirectory"` would tell solidity-coverage to look for `./secretDirectory/contracts`
 
 **Example .solcover.js config file**
 ```javascript
@@ -102,14 +97,15 @@ will probably error while coverage is being generated.
 
 **Using `require` in `migrations.js` files**: Truffle overloads Node's `require` function but
 implements a simplified search algorithm for node_modules packages 
-([see issue #383 at Truffle](https://github.com/trufflesuite/truffle/issues/383)). 
+([see Truffle issue #383](https://github.com/trufflesuite/truffle/issues/383)). 
 Because solidity-coverage copies an instrumented version of your project into a temporary folder, `require` 
 statements handled by Truffle internally won't resolve correctly.  
 
-**Coveralls / CodeCov**: These CI services take the Istanbul reports generated by solidity-coverage and display 
-line coverage. Istanbul's own html report publishes significantly more detail and can show whether 
-your tests actually reach all the conditional branches in your code. It can be found inside the 
-`coverage` folder at `index.html` after you run the tool. 
+**Using HDWalletProvider in `truffle.js`**: [See Truffle issue #348](https://github.com/trufflesuite/truffle/issues/348).
+HDWalletProvider tends to crash solidity-coverage and you should make sure its constructor isn't invoked while 
+coverage is running. An example workaround can be found at the zeppelin-solidity project 
+[here](https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/truffle.js#L8-L10), where a 
+coverage script sets a shell environment variable and `truffle.js` checks it before instantiating the wallet. 
 
 ### Examples