Update wording in general

Author: rbygrave

architecture/compare-hibernate.html

@@ -82,23 +82,22 @@ <h1><a href="/docs">Documentation</a> / <a href="/docs/architecture">Architectur
 
 <h2 id="jpa">JPA</h2>
 <p>
-  The issues discussed in the <a href="/architecture/compare-jpa">comparison with JPA</a> also apply to Hibernate.
-  The comparison here apply more specifically to Hibernate.
+  The issues discussed in this <a href="/architecture/compare-jpa">comparison with JPA</a> also apply to Hibernate.
 </p>
 
 <h2 id="max-rows">Honoring maxRows in SQL</h2>
 <p>
   Ebean ORM will always honor firstRows / maxRows in generated SQL. Once you include a join fetch
-  to a @OneToMany Hibernate stops implementing maxRows in SQL and instead brings all the rows back
+  to a @OneToMany, Hibernate stops implementing maxRows in SQL and instead brings all the rows back
   to the client (application server) and filters the results there.
 </p>
 <p>
   This means the database does not get the opportunity to optimise that query using maxRows
-  (via limit offset clause or similar) and so the DB query execution plan can be very different
-  by reducing the ability of the DB to use indexes and increasing the chances of full table scans.
+  (via limit offset clause or similar) so the DB query execution plan can be very different
+  by reducing the ability to use indexes and increasing the chance of a full table scan.
 </p>
 <p>
-  This also means significantly more data is pulled back from the DB to the client.
+  Significantly more data is pulled back from the DB to the client in this way.
 </p>
 <div class="row">
   <div class="col-md-6">
@@ -161,49 +160,47 @@ <h4 class="media-heading">Lazy loading beyond the context</h4>
 </div>
 
 <p>
-  Hibernate does not allow lazy loading beyond the end of it's Session scope and instead
-  throws <code>LazyInitialisationException</code>.
+  Hibernate does not allow lazy loading beyond the end of its' Session scope throwing <code>LazyInitialisationException</code>.
 </p>
 <h4>Ebean allows lazy loading beyond the initial scope</h4>
 <ul>
   <li>
-    The transaction isolation level of read committed is used as per the JPA spec. This means
-    there is no effective difference when we lazy load with using another JDBC transaction relative
+    The transaction isolation level of read committed is used as per the JPA spec. There is no effective difference when we lazy load with using another JDBC transaction relative
     to holding open a transaction (as typically required by Hibernate via "Open session in view").
   </li>
   <li>
     Ebean's entity beans have a reference back to their load context which enables subsequent
-    lazy loading to execute with the same PersistenceContext and also enables batch lazy loading.
+    lazy loading with the same PersistenceContext. (also enables batch lazy loading)
     This means the lazy loading still produces a consistent object graph (just as if it was loaded
     eagerly).
   </li>
   <li>
-    If you want to prevent lazy loading with Ebean you can do <code>query.setDisableLazyLoading(true)</code>.
+    To prevent lazy loading with Ebean, set <code>query.setDisableLazyLoading(true)</code>.
     This is useful when you want to use a partially populated bean and give it to a reflection based tool
     that converts it to JSON or DTO's etc.
   </li>
 </ul>
 <blockquote>
-  With Ebean lazy loading just works without any drama
+  With Ebean, lazy loading "just works" without any drama
 </blockquote>
 
 <p>&nbsp;</p>
 <h4 id="open-session-in-view">Open session in view</h4>
 <p>
   As a byproduct of Ebean supporting lazy loading (beyond transaction scope) Ebean does not require
-  the <code>"Open session in view"</code> pattern which is sometimes used with Hibernate.
+  the <code>"Open session in view"</code> pattern sometimes seen with Hibernate.
 </p>
 <p>
-  The "Open session in view" used with Hibernate has the effect of holding a transaction open for a
-  longer time relative to Ebean. This pattern is considered an anti-pattern by many and instead the
-  focus is on making sure service layer code has loaded everything that is needed on the entities
+  "Open session in view" has the effect of holding a transaction open for a
+  longer time relative to Ebean. This is considered an anti-pattern by many, with the
+  focus now being on ensuring the service layer has loaded everything needed on the entities
   (and this is code we don't need to write with Ebean).
 </p>
 
 <p>&nbsp;</p>
 <h2 id="history">SQL2011 @History vs Hibernate Envers</h2>
 <p>
-  Ebean's @History is a database centric approach mapping to SQL2011. Hibernate Envers is an application centric approach
+  Ebean's @History is a database-centric approach mapping to SQL2011. Hibernate Envers is an application centric approach
   which means that unlike @History bulk updates and external updates don't get included in auditing with Envers.
 </p>
 <div class="row">

architecture/compare-jpa.html

@@ -99,8 +99,8 @@ <h4 class="media-heading">Sessionless ORM</h4>
     </div>
 </div>
 <p>
-  JPA is architecture such that the entity beans must be <code>attached</code> to the <code>PersistenceContext</code>
-  in order for the entity beans to be <code>persisted</code>.
+  JPA is architected such that entity beans must be <code>attached</code> to the <code>PersistenceContext</code>
+  in order to be <code>persisted</code>.
 </p>
 <p>
   That is, JPA mandates <code>attach/detach</code> semantics. This has a number of consequences including:
@@ -117,9 +117,9 @@ <h3>Ebean architecture</h3>
 <ul>
   <li>No Entity manager, only manage transactions</li>
   <li>Dirty state on each entity bean</li>
-  <li>Persisting (save,delete) does not require the PersistenceContext</li>
+  <li>Persisting (save, delete) does not require the PersistenceContext</li>
   <li>PersistenceContext attached to the Transaction</li>
-  <li>Partially populated beans always expected</li>
+  <li>Partially populated beans are always expected</li>
 </ul>
 
 <hr/>
@@ -135,19 +135,19 @@ <h3>JDBC batch control</h3>
   <li>No ability to turn off cascade behavior (to take full control)</li>
 </ul>
 <p>
-  Using JDBC batch is important so that Ebean can get optimal performance when persisting. With Ebean
-  there is a JDBC batch buffer attached to the transaction and can seamlessly batch up persistence
+  Using JDBC batch is important so that we can get optimal performance when persisting. With Ebean
+  there is a JDBC batch buffer attached to the transaction that can seamlessly batch up persistence
   calls using JDBC batch.
 </p>
 <p>
-  Ebean provides full control over JDBC batch via the transaction including the
+  Ebean provides full control over JDBC batch via the transaction, including the
   <code>batch size</code>, <code>getGeneratedKeys</code>, and <code>cascade behavior</code>.
-  Unlike JPA with Ebean it is easy to fully control and optimise batch processing.
+  In contrast to JPA, it is easy to fully control and optimise batch processing with Ebean.
 </p>
 
 <h3>Transaction</h3>
 <p>
-  Additional to full control over JDBC batch Ebean provides the ability on a transaction to:
+  Ebean provides the ability on a transaction to:
 </p>
 <ul>
   <li>Register transaction callbacks (Post commit callback etc)</li>
@@ -158,7 +158,7 @@ <h3>Transaction</h3>
 <h3>Raw JDBC</h3>
 <p>
   Ebean provides access to the underlying <code>java.sql.Connection</code> for performing
-  raw JDBC if needed along with <code>transaction.addModification(table, ...)</code> method to
+  raw JDBC if needed along with a <code>transaction.addModification(table, ...)</code> method to
   tell Ebean what tables were modified for L2 cache invalidation.
 </p>
 <p>
@@ -168,17 +168,16 @@ <h3>Raw JDBC</h3>
 
 <h3>Transaction Isolation level</h3>
 <p>
-  Ebean lets you start a transaction at a higher Isolation level. JPA does not support this.
+  Ebean lets you start a transaction at a higher isolation level. JPA does not support this.
 </p>
 
 <h3>Stateless updates</h3>
 <p>
   Ebean allows us to populate a bean (or object graph) and <code>update()</code> without loading
-  the object object. This is useful in Rest like API's where we want to populate an entity object graph
+  the object object. This is useful in REST-like API's where we want to populate an entity object graph
   from JSON and perform an update.
 </p>
 
-
 <hr/>
 <h2 id="query-features">Query features</h2>
 
@@ -198,8 +197,8 @@ <h3>findPagedList</h3>
 <h3>findEach</h3>
 <p>
   JPA has no support for executing large queries. Ebean has <code>findEach</code>
-  for executing large queries (cursors / streaming) that takes into account the scope of the persistence context
-  , JDBC driver fetchSize and MySql specific treatment (because MySql has specific issues to deal with).
+  for executing large queries (cursors / streaming) that takes into account the scope of the persistence context,
+  JDBC driver, fetchSize, and MySql specific treatment (because MySql has specific issues to deal with).
 </p>
 
 <h3>findMap</h3>
@@ -248,14 +247,14 @@ <h3 id="jpql">JPQL</h3>
   some important features for controlling object graph construction from mixed sources (L2, L3 and DB).
 </p>
 <p>
-  In JPA the emphasis on annotations <code>FetchType.Eager</code> and <code>FetchType.Lazy</code>
-  and limitations in JPQL has put JPA in a bad position for optimising ORM queries and it will be
+  The emphasis on annotations <code>FetchType.Eager</code> and <code>FetchType.Lazy</code>
+  and limitations in JPQL has put JPA in a bad position for optimising ORM queries. It will be
   interesting if they can get to the level of control over object graph construction that Ebean supports.
 </p>
 
 <h3 id="type-safe-query">Type safe queries</h3>
 <p>
-  You could argue there is a bit more "ceremony" with JPA Criteria queries which makes the
+  One could argue there is a bit more "ceremony" with JPA Criteria queries that make the
   query more verbose and harder to read.
 </p>
 
@@ -292,11 +291,6 @@ <h5>JPA Criteria</h5>
   <a href="https://docs.jboss.org/hibernate/orm/5.0/topical/html/metamodelgen/MetamodelGenerator.html">JPA Query Meta model classes</a>
   in order to provide type safe query construction and execution.
 </p>
-<h5>QueryDSL</h5>
-<p>
-  I suspect many JPA users look to use <a href="http://www.querydsl.com/">QueryDSL</a> as a preference
-  over the standard JPA Criteria meta model objects.
-</p>
 
 <hr/>
 <h2 id="mapping">Mapping</h2>
@@ -314,7 +308,7 @@ <h3>@View</h3>
 <h3>Entities without @Id</h3>
 <p>
   Ebean does not require entities to have an @Id property. These entities are considered "read only" and
-  automatically bypass the persistence context. This entities are typically used for reporting purposes.
+  automatically bypass the persistence context. These entities are typically used for reporting purposes.
 </p>
 
 <h3>Naming convention</h3>

architecture/load-context.html

@@ -87,15 +87,15 @@ <h2 id="overview">Overview</h2>
   to the secondary queries.
 </p>
 
-<h2 id="batch-loading">Batch loading</h2>
+<h2 id="batch-loading">Batch Loading</h2>
 <p>
-  The Load context provides the batch loading mechanism. This solves the <a href="/docs/query/nplus1">N + 1</a> issue
-  for Ebean. As such it is one of the most important internal features of Ebean ORM.
+  The load context provides the batch loading mechanism, solving the <a href="/docs/query/nplus1">N + 1</a> issue
+  for Ebean. As such, it is one of the most important internal features of Ebean ORM.
 </p>
 
 <h2 id="propagate">Propagate query context</h2>
 <p>
-  When secondary queries load additional parts of the object graph Ebean propagates key query execution context
+  When secondary queries load additional parts of the object graph, Ebean propagates key query execution context
   from the <code>origin query</code> to the secondary queries including:
 </p>
 <ul>

architecture/orm-impedence-mismatch.html

@@ -82,25 +82,25 @@ <h1><a href="/docs">Documentation</a> / <a href="/docs/architecture">Architectur
 
 <h2 id="overview">ORM for OLTP only</h2>
 <p>
-  If you try to look at ORM from the viewpoint of trying to cover the entire feature set
-  of Relational Databases then yes there is absolutely a large mismatch.
+  If you seek to look for any ORM to cover the entire featureset
+  of a relational database, you'll find there is a mismatch.
 </p>
 <p>
-  Certainly for Ebean ORM and I'd suggest in general ORM is a poor abstraction for a large
-  feature set of Relational Databases and specifically ORM is not well placed to be a
+  ORMs are a poor abstraction for the large feature set of relational databases. Specifically, they are not well placed to be a
   good abstraction for <code>Reporting</code> and <code>Data Warehouse</code> features.
 </p>
 <p>
-  Ebean ORM is orientated towards OLTP with reasonably normalised schemas and well known
-  relationships but Relational Databases can do much more than this.
+  While Ebean ORM is oriented towards online transaction processing (OLTP) with reasonably normalized schemas and well known
+  relationships, relational databases as a technology can do much more than this.
 </p>
 
 <h2>Impedance details</h2>
 <p>
-  Lets continue to look into the ORM impedance details with the view that we are restricting
+  Lets continue to look into the ORM impedance details with the view of restricting
   ourselves to OLTP Databases.
 </p>
 
+<!-- Re-Add when there is content
 <h3>Inheritance</h3>
 <p>
 
@@ -109,7 +109,7 @@ <h3>Inheritance</h3>
 <h3>Object vs Relational relationships</h3>
 <p>
 
-</p>
+</p> -->
 
 <h3>Schema ownership conflict</h3>
 <p>