More language changes for docs

Author: hansjorg

md/asset-processor.md

@@ -1,10 +1,10 @@
 # asset processor
 
-Checks, validate and/or modify asset contents. An [AssetProcessor]({{defdocs}}/assets/AssetProcessor.html) is usually provided as a separated dependency.
+Checks, validates and/or modifies asset contents. An [AssetProcessor]({{defdocs}}/assets/AssetProcessor.html) is usually provided as a separate dependency.
 
-## how to use it?
+## usage
 
-First thing to do is to add the dependency:
+Start by adding the dependency to your ```pom.xml```:
 
 ```xml
   <dependency>
@@ -14,9 +14,10 @@ First thing to do is to add the dependency:
   </dependency>
 ```
 
-Did you see the **provided** scope? We just need the processor for development, because assets are processed at runtime. In ```prod```, assets are processed at built-time via Maven/Gradle plugin, so we don't need this library/dependency. This also, helps to keep our dependencies and the jar size small.
+Notice the **provided** scope. The processor is only required for development, since the assets are processed at runtime in this case. In ```prod```, assets are processed at build-time via the Maven or Gradle plugins, so the dependency is not needed there. This also helps to keep the number of dependencies and the jar size smaller.
+
+After the dependency is declared, all that's needed is to add the processor to the pipeline:
 
-Now we have the dependency all we have to do is to add it to our pipeline:
 
 ```text
 assets {
@@ -28,7 +29,7 @@ assets {
 
 ## configuration
 
-It is possible to configure or set options too:
+It's possible to configure or set options as well:
 
 ```text
 assets {
@@ -42,7 +43,7 @@ assets {
 }
 ```
 
-Previous example, set a ```foo``` property to ```bar```! Options can be set per environment too:
+The previous example sets the ```foo``` property to ```bar```. Options can be set per environment as well:
 
 ```text
 assets {
@@ -62,11 +63,11 @@ assets {
 }
 ```
 
-Here, in ```dev``` processor has two properties: ```foo:foo``` and ```bar:bar```, while in ```dist``` the processor only has ```foo:bar```
+In this example, the processor will have two properties in the ```dev``` environment: ```foo:foo``` and ```bar:bar```, while in ```dist``` the processor will only have ```foo:bar```
 
 ## binding
 
-The ```my-processor``` will be resolved it to: ```org.jooby.assets.MyProcessor``` class. The processor name is converted to ```MyProcessor```, it converts the hyphenated name to upper camel and by default processors are defined in the ```org.jooby.assets``` package.
+The ```my-processor``` token will be resolved to the: ```org.jooby.assets.MyProcessor``` class. The processor name is converted to ```MyProcessor``` by converting the hyphenated name to upper camel case and by placing it in the ```org.jooby.assets``` package (a default for processors).
 
 A custom binding is provided via the ```class``` property:
 
@@ -86,9 +87,9 @@ assets {
 
 Contributes new or dynamically generated content to a ```fileset```. Content generated by an aggregator might be processed by an {@link AssetProcessor}.
 
-## how to use it?
+## usage
 
-First thing to do is to add the dependency:
+Start by adding the dependency to your ```pom.xml```:
 
 ```xml
 <dependency>
@@ -99,9 +100,9 @@ First thing to do is to add the dependency:
 
 ```
 
-Did you see the **provided** scope? We just need the aggregator for development, because assets are processed at runtime. In ```prod```, assets are processed at built-time via Maven/Gradle plugin, so we don't need it. This also, helps to keep our dependencies and the jar size small.
+Notice the **provided** scope. The aggregator is only required for development, since the assets are processed at runtime in this case. In ```prod```, assets are processed at build-time via the Maven or Gradle plugins, so the dependency is not needed there. This also helps to keep the number of dependencies and the jar size smaller.
 
-Now we have the dependency all we have to do is to add the ```svg-sprites``` aggregator to a fileset:
+After the dependency is declared, all that's needed is to add the ```svg-sprites``` aggregator to a fileset:
 
 ```
 assets {
@@ -124,7 +125,7 @@ assets {
 }
 ```
 
-Here for example, the ```svg-sprites``` aggregator contributes the ```css/sprite.css``` file to the ```home``` fileset. The fileset then looks like:
+In this example, the ```svg-sprites``` aggregator contributes the ```css/sprite.css``` file to the ```home``` fileset. The fileset then looks like:
 
 ```
 assets {
@@ -138,7 +139,7 @@ assets {
 }
 ```
 
-It replaces the aggregator name with one or more files from [AssetAggregator.fileset]({{defdocs}}/assets/AssetAggregator.html#fileset--) method.
+It replaces the aggregator name with one or more files from the [AssetAggregator.fileset]({{defdocs}}/assets/AssetAggregator.html#fileset--) method.
 
 # available processors
 

md/assets-require.md

@@ -1 +1 @@
-Make sure you already setup the [assets module](https://github.com/jooby-project/jooby/tree/master/jooby-assets) in your project!
+Make sure you've already set up the [assets module](https://github.com/jooby-project/jooby/tree/master/jooby-assets) in your project!

md/async.md

@@ -24,9 +24,9 @@ The **worker thread** pool is provided by one of the supported web servers: {{ne
 
 The web server can accept as many connections it can (as its on non blocking) while the worker thread might block.
 
-The default worker thread pool is `20/100`. The optimal size depends on the **business** and **work load** your application is suppose to handle. We suggest you to start with the default setup and see how it goes, later you can reduce or increase the thread pool.
+The default worker thread pool is `20/100`. The optimal size depends on the **business** and **work load** your application is supposed to handle. It's recommended to start with the default setup and then tune the size of the thread pool if the need arises.
 
-In {{jooby}} we favor simplicity over complexity that is why your **code** can block, still there are more advanced options that allow you to build async and reactive applications.
+{{jooby}} favors simplicity over complexity hence allowing your **code** to block. However, it also provides you with more advanced options that will allow you to build async and reactive applications.
 
 ## deferred
 
@@ -97,7 +97,7 @@ MVC API:
 
 The [AsyncMapper]({{defdocs}}/AsyncMapper.html) converts `java.util.concurrent.Callable` and `java.util.concurrent.CompletableFuture` objects to {{deferred}} objects.
 
-Another important thing to notice is that the deferred run in the **caller thread** (i.e. worker thread), so by default there is **no context switch** involved while running a {{deferred}} result:
+Another important thing to notice is that the deferred will run in the **caller thread** (i.e. worker thread), so by default there is **no context switch** involved in obtaining a {{deferred}} result:
 
 ```java
 {
@@ -111,11 +111,11 @@ Another important thing to notice is that the deferred run in the **caller threa
 }
 ```
 
-You might see this as a bad thing at first, but it's actually a good decision, because:
+This might not seem optimal at first, but there are some benefits to this:
 
-* It is super easy to setup a default executor (we will see how soon)
+* It makes it very easy to set up a default executor (this will be explained shortly)
 
-* Provides better integration with async & reactive libraries. A `direct` executor avoid the need of switching to a new thread and then probably dispatch (again) to a different thread provided by a library.
+* It provides better integration with async & reactive libraries. A `direct` executor avoids the need of switching to a new thread and then probably dispatch (again) to a different thread provided by a library.
 
 ## executor
 
@@ -220,7 +220,7 @@ The **"promise"** version of the {{deferred}} object is a key concept for integr
 
 ## advanced configuration
 
-Suppose you want to build a truly async application and after a **deep analysis** of your business you realize your application need to:
+Suppose you want to build a truly async application and after a **deep analysis** of your business demands you realize your application needs to:
 
 * Access a database
 * Call a remote service
@@ -235,7 +235,7 @@ server.threads.Min = ${runtime.processors}
 server.threads.Max = ${runtime.processors}
 ```
 
-With this change, you need to be careful and **don't run blocking code** on routes anymore. Otherwise performance will be affected.
+With this change, you need to be careful to **avoid any blocking code** on routes, otherwise performance will suffer.
 
 Let's create a custom thread pool for each blocking access:
 
@@ -247,11 +247,11 @@ Let's create a custom thread pool for each blocking access:
 }
 ```
 
-For `database` access, we use a `cached` executor that will grow without a limit but free and release threads that are idle after `60s`.
+For `database` access, we use a `cached` executor which will grow without a limit but free and release threads that are idle after `60s`.
 
-For `remote` service, we use a `fixed` executor of `32` threads. The number here: `32` is just a random number for the purpose of the example.
+For `remote` service, we use a `fixed` executor of `32` threads. The number `32` is just a random number for the purpose of the example.
 
-For `intensive` computation, we use a `single` thread executor. Computation is too expensive and we want **one and only one** running at any time.
+For `intensive` computations, we use a `single` thread executor. Computation is too expensive and we want **one and only one** running at any time.
 
 ```java
 {
@@ -277,7 +277,7 @@ For `intensive` computation, we use a `single` thread executor. Computation is t
 }
 ```
 
-Here is the same example with [rx java](https://github.com/ReactiveX/RxJava):
+Here's the same example with [rx java](https://github.com/ReactiveX/RxJava):
 
 ```java
 {
@@ -316,11 +316,11 @@ Here is the same example with [rx java](https://github.com/ReactiveX/RxJava):
 
 The main differences are:
 
-* we keep the default executor: `direct`. So we don't create a new thread and avoid context switching.
-* we use {{deferred}} object as `promise` and integrate with [rx java](https://github.com/ReactiveX/RxJava).
-* different thread pool semantic is done via [rx schedulers](http://reactivex.io/documentation/scheduler.html).
+* the default executor is kept `direct`. No new thread is created and context switching is avoided.
+* the {{deferred}} object is used as a `promise` and integrate with [rx java](https://github.com/ReactiveX/RxJava).
+* different thread pool semantics is achieved with the help of [rx schedulers](http://reactivex.io/documentation/scheduler.html).
 
-This is just one more example to demonstrate the value of the {{deferred}} object, because we provide an [rxjava](/doc/rxjava) module which takes care of binding {{deferred}} object into `Observables`.
+This is just another example to demonstrate the value of the {{deferred}} object, since a [rxjava](/doc/rxjava) module is provided which takes care of binding the {{deferred}} object into `Observables`.
 
 That sums up everything about the {{deferred}} object. It allows you to build async and reactive applications and at the same time: **keep it simple** (a Jooby design goal).
 

md/available-modules.md

@@ -9,15 +9,15 @@
 * [gson](https://github.com/jooby-project/jooby/tree/master/jooby-gson): JSON supports via Gson.
 
 ## template engines
-* [handlebars/mustache](https://github.com/jooby-project/jooby/tree/master/jooby-hbs): logic less and semantic Mustache templates.
+* [handlebars/mustache](https://github.com/jooby-project/jooby/tree/master/jooby-hbs): logic-less and semantic Mustache templates.
 * [freemarker](https://github.com/jooby-project/jooby/tree/master/jooby-ftl): render templates with FreeMarker.
 
 ## session
-* [redis](https://github.com/jooby-project/jooby/tree/master/jooby-jedis/#redis-session-store): HTTP session on {{redis}}.
-* [memcached](https://github.com/jooby-project/jooby/tree/master/jooby-spymemcached/#session-store): HTTP session on {{memcached}}.
-* [mongodb](https://github.com/jooby-project/jooby/tree/master/jooby-mongodb/#mongodb-session-store): HTTP session on {{mongodb}}.
-* [hazelcast](https://github.com/jooby-project/jooby/tree/master/jooby-hazelcast/#session-store): HTTP session on {{hazelcast}}.
-* [ehcache](https://github.com/jooby-project/jooby/tree/master/jooby-ehcache/#session-store): HTTP session on {{ehcache}}.
+* [redis](https://github.com/jooby-project/jooby/tree/master/jooby-jedis/#redis-session-store): HTTP session store for {{redis}}.
+* [memcached](https://github.com/jooby-project/jooby/tree/master/jooby-spymemcached/#session-store): HTTP session store for {{memcached}}.
+* [mongodb](https://github.com/jooby-project/jooby/tree/master/jooby-mongodb/#mongodb-session-store): HTTP session store for {{mongodb}}.
+* [hazelcast](https://github.com/jooby-project/jooby/tree/master/jooby-hazelcast/#session-store): HTTP session store for {{hazelcast}}.
+* [ehcache](https://github.com/jooby-project/jooby/tree/master/jooby-ehcache/#session-store): HTTP session store for {{ehcache}}.
 
 ## sql
 * [jdbc](https://github.com/jooby-project/jooby/tree/master/jooby-jdbc): high performance connection pool for jdbc via {{hikari}}.

md/capsule.md

@@ -24,7 +24,7 @@ The ```capsule``` Maven profile is activated by the presence of the ```src/etc/c
 
 ## options
 
-Integration provides some defaults, which are listed here:
+The integration provides the following defaults:
 
 ```xml
 <properties>

md/conf.md

@@ -2,7 +2,7 @@
 
 Jooby delegates configuration management to the [Config library](https://github.com/typesafehub/config).
 
-By defaults Jooby expects to find an ```application.conf``` file at the root of classpath. You can find the `.conf` file under the `conf` classpath directory.
+By default, Jooby expects to find an ```application.conf``` file at the root of the classpath. You can find the `.conf` file under the `conf` classpath directory.
 
 ## getting properties
 
@@ -63,11 +63,11 @@ You're free to inject the entire ```com.typesafe.config.Config``` object or `sub
 
 ## environment
 
-Jooby internals and the module system rely on the ```application.env``` property. By defaults, this property is set to: ```dev```.
+Jooby internals and the module system rely on the ```application.env``` property. By default, this property is set to: ```dev```.
 
 This special property is represented at runtime with the [Env]({{apidocs}}/org/jooby/Env.html) class.
 
-For example: a module might decided to create a connection pool, cache, etc when ```application.env``` isn't set to `dev`.
+For example: a module might decided to create a connection pool, cache, etc. when ```application.env``` isn't set to `dev`.
 
 The `application.env` property can be set as command line argument as well:
 

md/cors.md

@@ -1,6 +1,6 @@
 ## cors
 
-Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources
+Cross-origin resource sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS)) is a mechanism that allows restricted resources
 (e.g. fonts, JavaScript, etc.) on a web page to be requested from another domain outside the domain from which the resource originated.
 
 ### usage
@@ -62,5 +62,5 @@ cors {
 }
 ```
 
-```CORS``` options are represented at runtime by [Cors]({{defdocs}}/handlers/Cors.html).
+```CORS``` options are represented at runtime by the [Cors]({{defdocs}}/handlers/Cors.html) handler.
 

md/doc/caches/caches.md

@@ -1,24 +1,24 @@
 # caches
 
-Find here access to various caches solutions including {{redis}}, {{memcached}}, etc..., but also pure Java solutions like {{hazelcast}} or {{ehcache}}.
+These modules provide access to various cache solutions including {{redis}}, {{memcached}}, etc., as well as to pure Java solutions like {{hazelcast}} and {{ehcache}}.
 
 ## redis
 
-[Jedis](/doc/jedis) provides access to a {{redis}} cache via {{jedis}} driver.
+[Jedis](/doc/jedis) provides access to a {{redis}} cache via the {{jedis}} driver.
 
 ## memcached
 
-[Spymemcached](/doc/spymemcached) provides access to a {{memcached}} cache via {{spymemcached}} driver.
+[Spymemcached](/doc/spymemcached) provides access to a {{memcached}} cache via the {{spymemcached}} driver.
 
 ## caffeine
-[Caffeine](/doc/caffeine): [Caffeine](https://github.com/ben-manes/caffeine) caches.
+[Caffeine](/doc/caffeine): [Caffeine](https://github.com/ben-manes/caffeine) cache support.
 
 ## ehcache
-[Ehcache](/doc/ehcache): {{ehcache}} caches.
+[Ehcache](/doc/ehcache): {{ehcache}} support.
 
 ## guava
-[Guava](/doc/guava-cache): [Guava](https://github.com/google/guava) caches.
+[Guava](/doc/guava-cache): [Guava](https://github.com/google/guava) cache support.
 
 ## hazelcast
 
-[Hazelcast](/doc/hazelcast): {{hazelcast}} caches.
+[Hazelcast](/doc/hazelcast): {{hazelcast}} cache support.

md/doc/datastore/datastore.md

@@ -1,6 +1,6 @@
 # data store
 
-Find access to various data store including relational, documented oriented, key/value, etc.
+These are modules providing access to various data stores, including relational, document oriented, key/value stores, etc.
 
 # jdbc
 
@@ -32,7 +32,7 @@ The [querydsl-jpa](/doc/querydsl-jpa) provides unified Queries for JPA. [Queryds
 
 ## requery
 
-[Requery](/doc/requery) a light but powerful object mapping and SQL generator for Java/Kotlin/Android with RxJava and Java 8 support. Easily map to or create databases, perform queries and updates from any platform that uses Java.
+[Requery](/doc/requery) is a light but powerful object mapping and SQL generator for Java/Kotlin/Android with RxJava and Java 8 support. Easily map to or create databases, perform queries and updates from any platform that uses Java.
 
 ## rxjdbc
 

md/doc/hbs/hbs.md

@@ -1,6 +1,6 @@
 # handlebars
 
-Logic less and semantic templates via {{handlebars}}.
+Logic-less and semantic templates via [Handlebars.java](https://github.com/jknack/handlebars.java).
 
 ## exports
 
@@ -33,7 +33,7 @@ public/index.html:
 {{model}}
 ```
 
-Templates are loaded from root of classpath: ```/``` and must end with: ```.html``` file extension.
+Templates are loaded from the root of the classpath: ```/``` and must end with: ```.html``` file extension.
 
 ## request locals
 
@@ -94,7 +94,7 @@ Templates are loaded from the root of classpath and must end with ```.html```. Y
 
 Cache is OFF when ```env=dev``` (useful for template reloading), otherwise is ON.
 
-Cache is backed by [Guava](https://github.com/google/guava) and the default cache will expire after ```100``` entries.
+The cache is backed by [Guava](https://github.com/google/guava) and the default cache will expire after ```100``` entries.
 
 If ```100``` entries is not enough or you need a more advanced cache setting, just set the
 ```hbs.cache``` option: