some changes in wording

Author: dmitry@jet.com

docs/content/comparison.fsx

@@ -3,28 +3,28 @@
 A comparison on SQL Server data access methods
 ==============================================
 
-Type providers + Query Expressions 
+Type providers + Query Expressions
 -----------------------------------------
 
- F# Query Expressions (aka LINQ 2.0) is lovely and useful technology. It makes writing data access code a pleasant exercise. 
- There are several different implementations available: [SQLProvider][sql] (recent community effort), [SqlDataConnection][linq2sql]/[DbmlFile][dbml] 
- and [SqlEntityConnection][ef]/[EdmxFile][edmx].  
- 
- But I would like to point out some reasons you might prefer SqlCommandProvider over those. 
- Take a look at this  [StackOverflow issue][soissue]. There are dozens of similar questions (hundreds if you include C# LINQ which is essentially 
- the same issue). 
- 
+ F# Query Expressions (aka LINQ 2.0) is lovely and useful technology. It makes writing data access code a pleasant exercise.
+ There are several different implementations available: [SQLProvider][sql] (recent community effort), [SqlDataConnection][linq2sql]/[DbmlFile][dbml]
+ and [SqlEntityConnection][ef]/[EdmxFile][edmx].
+
+ But I would like to point out some reasons you might prefer SqlCommandProvider over those.
+ Take a look at this  [StackOverflow issue][soissue]. There are dozens of similar questions (hundreds if you include C# LINQ which is essentially
+ the same issue).
+
  So, what's a deal? The thing is, you can have perfectly valid F# code that compiles but still fails at run-time because of
- unsupported F#-to-SQL translation semantics. Contrary, SqlCommandProvider offers "What You See Is What You Get" approach. 
- Once F# code involving SqlCommandProvider passes compilation stage you are guaranteed to have valid executable (both F# code and T-SQL). 
- 
- Lack of control and opaqueness of F#-to-SQL conversion spells performance problems too.  
- At times developers are really frustrated by ineffective T-SQL code generated by type providers (most of EF users are aware of this issue). 
- Evolution and changes in T-SQL code generated by type provider may present certain problems too. 
- A data access code that is performing well today can become suboptimal tomorrow. 
- SqlCommandProvider gives you direct access to full power of T-SQL scripting including the latest features which are often 
- unavailable in type providers because they target older or different versions of the system. 
- 
+ unsupported F#-to-SQL translation semantics. Contrary, SqlCommandProvider offers "What You See Is What You Get" approach.
+ Once F# code involving SqlCommandProvider passes compilation stage you are guaranteed to have valid executable (both F# code and T-SQL).
+
+ Lack of control and opaqueness of F#-to-SQL conversion spells performance problems too.
+ At times developers are really frustrated by ineffective T-SQL code generated by type providers (most of EF users are aware of this issue).
+ Evolution and changes in T-SQL code generated by type provider may present certain problems too.
+ A data access code that is performing well today can become suboptimal tomorrow.
+ SqlCommandProvider gives you direct access to full power of T-SQL scripting including the latest features which are often
+ unavailable in type providers because they target older or different versions of the system.
+
    [sql]: http://github.com/fsprojects/SQLProvider
    [linq2sql]: http://msdn.microsoft.com/en-us/library/hh361033.aspx
    [dbml]: http://msdn.microsoft.com/en-us/library/hh361039.aspx
@@ -34,41 +34,40 @@ Type providers + Query Expressions
 
 ### Common for all TypeProviders
 
-- You write just logic code, not POCO-objects and mappings
-- If your database changes, your code breaks on compile time
+- You write logic, not POCO-objects and mappings
+- If your database changes, your code breaks at compile time
 - No SQL-injection vulnerabilities
 - Commit to existing transactions so you can mix with other technologies
-- You can call stored procedures if needed.
-- Supports joins and nested in-queries so you can avoid "n+1 database hits" problems
+- You can call stored procedures if needed
+- Joins and nested in-queries are supported so you can avoid "n+1 database hits" problems
 
 ### FSharp.Data.SqlClient
 
 Good:
 
-- User has control of SQL-clauses
-- So you can hit database indexes with complex queries
-- SQL-syntax is already familiar for many
+- User has full control of SQL
+- Which allows full utilization of database indexes with complex queries
+- SQL syntax is already familiar for many
+- Exposes database objects directly in code
 - Supports async database operations
-- Use it e.g. for data processing backends
+- Used in production for enterprise development for years
 - Open source
 
 Not so good:
 
-- By default supports only Microsoft SQLServer and its SQL.
+- By default supports only Microsoft SQLServer and T-SQL
 - Code overhead if you have a large amount of different small operations
 - Doesn't generate domain model for work with C#
 
-
 ### SQLProvider
 
 Good:
 
 - Supports any database (MSSQL, MySQL, Postgre, Oracle, Odbc, ...)
 - Changing the database is not actually huge work
-- Makes effective simple SQL 
+- Makes effective simple SQL
 - Supports async database operations
-- Use it e.g. for web servers
-- User's code stays simple
+- Simplifies user code
 - Open source
 
 Not so good:
@@ -77,6 +76,7 @@ Not so good:
 - FSharp/LINQ query-syntax is a learning curve
 - Doesn't generate domain model for work with C#
 - Most LINQ-operations supported, but not yet complex group-by scenarios
+- Updates in complex scenarios can be a pain
 
 ### SqlDataConnection
 
@@ -87,7 +87,7 @@ Good:
 
 Not so good:
 
-- Generates EF-models on background
+- Generates EF-models in background
 - Not dynamic
 - Doesn't scale to large databases
 - FSharp/LINQ query-syntax is a learning curve
@@ -97,26 +97,26 @@ Not so good:
 [Dapper](https://code.google.com/p/dapper-dot-net/)
 -----------------------------------------
 
-FSharp.Data.SqlClient is much closer to the family of micro-ORMs rather than complete solutions like EntityFramework and NHibernate, 
+FSharp.Data.SqlClient is much closer to the family of micro-ORMs rather than complete solutions like EntityFramework and NHibernate,
 hence comparison with the best of the breed - Dapper.
 
-Dapper is a micro-ORM by StackOverflow with a main goal of being extremely fast. Here is a [description](http://stackoverflow.com/tags/dapper/info) 
+Dapper is a micro-ORM by StackOverflow with a main goal of being extremely fast. Here is a [description](http://stackoverflow.com/tags/dapper/info)
 from StackOverflow itself:
 
->dapper is a micro-ORM, offering core parameterization and materialization services, but (by design) not the full breadth of services that you might 
-expect in a full ORM such as LINQ-to-SQL or Entity Framework. Instead, it focuses on making the materialization as fast as possible, with no overheads 
+>dapper is a micro-ORM, offering core parameterization and materialization services, but (by design) not the full breadth of services that you might
+expect in a full ORM such as LINQ-to-SQL or Entity Framework. Instead, it focuses on making the materialization as fast as possible, with no overheads
 from things like identity managers - just "run this query and give me the (typed) data".
 
-Let's start with performance to get it out of the way. 
+Let's start with performance to get it out of the way.
 
-Dapper comes with an excellent [benchmark](https://code.google.com/p/dapper-dot-net/source/browse/Tests/PerformanceTests.cs). 
+Dapper comes with an excellent [benchmark](https://code.google.com/p/dapper-dot-net/source/browse/Tests/PerformanceTests.cs).
 The focus of the test is on deserialization. Here is how FSHarp.Data.SqlClient compares with all major .Net ORMs:
 
 <img src="img/dapper.png"/>
 
-Tests were executed against SqlExpress 2012 so the numbers are a bit higher than what you can see on 
+Tests were executed against SqlExpress 2012 so the numbers are a bit higher than what you can see on
 [Dapper page](https://github.com/SamSaffron/dapper-dot-net#performance-of-select-mapping-over-500-iterations---poco-serialization).
-A test retrieves single record with 13 properties by random id 500 times and deserializes it. Runs for different ORMs are mixed up randomly. 
+A test retrieves single record with 13 properties by random id 500 times and deserializes it. Runs for different ORMs are mixed up randomly.
 All executions are synchronous.
 
 Note that we didn't put any specific effort into improving FSharp.Data.SqlClient performance for this test. The very nature of type providers helps to produce
@@ -127,32 +127,32 @@ Keeping in mind that FSharp.Data.SqlClient is not strictly an ORM in commonly un
 
 * Because result types are auto-generated, FSharp.Data.SqlClient doesn't support so-called [multi-mapping](http://stackoverflow.com/a/6001902/862313)
 * As FSharp.Data.SqlClient is based on features specific for Sql Server 2012; Dapper provides better range of supported scenarios, including Mono
-* Other side of this is that FSharp.Data.SqlClient fully supports SqlServer-specific types like [hierarchyId](http://technet.microsoft.com/en-us/library/bb677173.aspx) and 
+* Other side of this is that FSharp.Data.SqlClient fully supports SqlServer-specific types like [hierarchyId](http://technet.microsoft.com/en-us/library/bb677173.aspx) and
 [spatial types](http://blogs.msdn.com/b/adonet/archive/2013/12/09/microsoft-sqlserver-types-nuget-package-spatial-on-azure.aspx), which Dapper does not
-* FSharp.Data.SqlClient fully supports User-Defined Table Types for input parameters with no additional coding required, 
+* FSharp.Data.SqlClient fully supports User-Defined Table Types for input parameters with no additional coding required,
 [as opposed to Dapper](http://stackoverflow.com/questions/6232978/does-dapper-support-sql-2008-table-valued-parameters)
-* Dapper intentionally  has no support for `SqlConnection` management; FSharp.Data.SqlClient encapsulates `SqlConnection` 
+* Dapper intentionally  has no support for `SqlConnection` management; FSharp.Data.SqlClient encapsulates `SqlConnection`
 life-cycle including asynchronous scenarios while optionally accepting external `SqlTransaction`.
 
 Following FSharp.Data.SqlClient features are unique:
 
 * Reasonable auto-generated result type definition so there is no need to define it in code
 * This type also comes with `IDictionary<string,obj>` and `DynamicObject` implementation
-* Sql command is just a string for other ORMs, while FSHarp.Data.SqlClient verifies it and figures out input parameters and output types 
+* Sql command is just a string for other ORMs, while FSHarp.Data.SqlClient verifies it and figures out input parameters and output types
 so design-time experience is simply unparalleled
-* Design-time verification means less run-time tests, less yak shaving synchronizing database schema with code definitions, and earliest possible 
+* Design-time verification means less run-time tests, less yak shaving synchronizing database schema with code definitions, and earliest possible
 identification of bugs and mismatches
 * `SqlProgrammabilityProvider` lets user to explore stored procedures and user-defined functions right from the code with IntelliSense
 
 
-It is my believe that FSharp.Data.SqlClient comes closest to the mission of micro-ORM - to make conversion between data stored in database and .Net run-time types as painless as possible 
+It is my believe that FSharp.Data.SqlClient comes closest to the mission of micro-ORM - to make conversion between data stored in database and .Net run-time types as painless as possible
 while keeping away from [object-relational impedance mismatch](http://en.wikipedia.org/wiki/Object-relational_impedance_mismatch)
 as described in famous blog [The Vietnam of Computer Science](http://blogs.tedneward.com/2006/06/26/The+Vietnam+Of+Computer+Science.aspx) by Ted Neward.
 
 [Generating strongly typed DataSets](http://msdn.microsoft.com/en-us/library/wha85tzb.aspx)
 -----------------------------------------
 
-Using strongly typed DataSets requires creation of XSD schema which then used to generate C# code. Dubious pleasure of hand-crafting XSD aside, 
+Using strongly typed DataSets requires creation of XSD schema which then used to generate C# code. Dubious pleasure of hand-crafting XSD aside,
 this traditional technique suffers from the same limitation as Entity Framework and such when compared to FSharp.Data.SqlClient:
 no design-time interaction with model database - it is up to a user to keep definitions and database schema in sync.