documentation improvements

Author: ptrthomas

README.md

@@ -91,8 +91,6 @@ Karate requires [Java](http://www.oracle.com/technetwork/java/javase/downloads/i
 
 Karate is designed so that you can choose between the [Apache](https://hc.apache.org/index.html) or [Jersey](https://jersey.java.net) HTTP client implementations.
 
-Prefer `karate-apache` unless you run into class-loading conflicts, for example - if an older version of the Apache libraries are being used within your project.
-
 So you need two `<dependencies>`:
 
 ```xml
@@ -109,6 +107,8 @@ So you need two `<dependencies>`:
     <scope>test</scope>
 </dependency>
 ```
+And if you run into class-loading conflicts, for example if an older version of the Apache libraries are being used within your project - then use `karate-jersey` instead of `karate-apache`.
+
 ### TestNG instead of JUnit
 If you want to use [TestNG](http://testng.org), use the artifactId [`karate-testng`](https://mvnrepository.com/artifact/com.intuit.karate/karate-testng). If you are starting a project from scratch, we strongly recommend that you use JUnit. Do note that [dynamic tables](#data-driven-features), [data-driven](#data-driven-tests) testing and [tag-groups](#cucumber-tags) are built-in to Karate, so that you don't need to depend on things like the TestNG [`@DataProvider`](http://testng.org/doc/documentation-main.html#parameters-dataproviders) anymore.
 

karate-demo/README.md

@@ -14,7 +14,7 @@ as well as demonstrate various Karate features and best-practices.
 [`call-json-array.feature`](src/test/java/demo/callarray/call-json-array.feature) | This example loads JSON data from a file and uses it to call a `*.feature` file in a loop. This approach can enable very dynamic data-driven tests, since there are a variety of ways by which you can create the JSON data, for example by calling custom Java code.
 [`call-table.feature`](src/test/java/demo/calltable/call-table.feature) | This is a great example of how Karate combines with Cucumber and JsonPath to give you an extremely readable data-driven test. Karate's [`table`](https://github.com/intuit/karate#table) keyword is a super-elegant and readable way to create JSON arrays, perfect for setting up all manner of data-driven tests.
 [`call-dynamic-json.feature`](src/test/java/demo/calldynamic/call-dynamic-json.feature) | Shows how to dynamically create a JSON array and then use it to call a `*.feature` file in a loop. In this example, the JSON is created using a JavaScript function, but it can very well be the response from an HTTP call, the result of a JsonPath expression or even a List of HashMap-s acquired by [calling Java](https://github.com/intuit/karate#calling-java). This test actually calls a second `*.feature` file in a loop to validate a 'get by id'. Using JsonPath and [`match each`](https://github.com/intuit/karate#match-each) to validate all items within a JSON array is also demonstrated.
-[`call-once.feature`](src/test/java/demo/callonce/call-once.feature) | `Background:` steps in Cucumber are re-run for every `Scenario:` and unfortunately even for every `Examples:` row in any `Scenario Outline:` present. This is clearly not ideal especially for HTTP calls that are expensive and time-consuming and [this is still an open issue](https://github.com/cucumber/cucumber-jvm/issues/515) for the Cucumber-JVM project. Fortunately you can elegantly work-around this limitation of Cucumber with the help of Karate's Java interop.
+[`call-once.feature`](src/test/java/demo/callonce/call-once.feature) | `Background:` steps in Cucumber are re-run for every `Scenario:` and unfortunately even for every `Examples:` row in any `Scenario Outline:` present. This is clearly not ideal especially for HTTP calls that are expensive and time-consuming and [this is still an open issue](https://github.com/cucumber/cucumber-jvm/issues/515) for the Cucumber-JVM project. Fortunately you can elegantly work-around this limitation of Cucumber with the help of Karate's [Java interop](https://github.com/intuit/karate#calling-java).
 
 ## Best Practices
 | File | Demonstrates

karate-demo/src/test/java/demo/callonce/call-once.feature

@@ -1,4 +1,4 @@
-Feature: how to implement 'run only once' or set-up that behaves like @BeforeClass
+Feature: test set-up routines that run only once, similar to how @BeforeClass works
 
 Background: