Merge pull request #178 from graben/doc

Enhance documentation and correct spelling

README.md

@@ -24,14 +24,14 @@ to customize the Narayana configuration. See the
 [NarayanaProperties](narayana-spring-boot-core/src/main/java/dev/snowdrop/boot/narayana/core/properties/NarayanaProperties.java)
 Javadoc for complete details.
 
-> Only a limited number of Narayana configuration options are exposed via `application.properties`. For a more
-more complex configuration you can provide a `jbossts-properties.xml` file. To get more details, please, consult
+> Only a limited number of Narayana configuration options are exposed via `application.properties`. For a more complex
+configuration you can provide a `jbossts-properties.xml` file. To get more details, please, consult
 Narayana project [documentation](http://narayana.io/docs/project/index.html).
 
 > To ensure that multiple transaction managers can safely coordinate the same resource managers, each Narayana instance
 must be configured with a unique ID. By default, this ID is set to 1. To ensure uniqueness in production, you should
 configure the `narayana.node-identifier` property with a different value for each instance of your application. This value
-must not exceed a length of 28 bytes. To ensure that the value is shorten to a valid length by hashing with SHA-224 and encoding
+must not exceed a length of 28 bytes. To ensure that the value is shortened to a valid length by hashing with SHA-224 and encoding
 with base64, configure `narayana.shorten-node-identifier-if-necessary` property to true. Be aware, this may result in duplicate
 strings which break the uniqueness that is mandatory for safe transaction usage!
 
@@ -52,11 +52,17 @@ public class Application {
 
 # Using databases
 
-By default Narayana Transactional driver is used to enlist a relational database to a JTA transaction which provides a basic XAResource enlistment and recovery.
+By default, [Narayana Transactional driver](https://www.narayana.io/docs/api/com/arjuna/ats/jdbc/TransactionalDriver.html)
+is used to enlist a relational database to a JTA transaction which provides a basic XAResource enlistment and recovery as
+well as a simple pooling mechanism.
+
+> Be aware that Narayana Transactional driver automatically set transaction isolation level to `Connection.TRANSACTION_SERIALIZABLE`,
+which might change default behaviour of the used database system!
+For example, [Oracle Database](narayana-spring-boot-starter-it/src/test/resources/oracle-initscript.sql)
 
 ## Add pooling
 
-If you need a more sophisticated connection management, we advice you to use [agroal-spring-boot-starter](https://agroal.github.io)
+If you need a more sophisticated connection management, we advise you to use [agroal-spring-boot-starter](https://agroal.github.io)
 which provides connection pooling and many other features. To enable Agroal add the following dependency to your application configuration:
 ```xml
 <dependency>
@@ -73,16 +79,26 @@ All Agroal configuration properties described in its [documentation](https://agr
 This Narayana starter supports two ways to enlist a messaging broker to a JTA transaction: plain connection
 factory and MessagingHub pooled connection factory.
 
-By default Narayana Connection Proxy around the JMS connection factory is used which provides a basic XAResource enlistment and recovery.
+By default, [Narayana Connection Proxy](https://www.narayana.io/docs/api/org/jboss/narayana/jta/jms/ConnectionFactoryProxy.html)
+around the JMS connection factory is used which provides a basic XAResource enlistment and recovery.
 
 ## Add pooling
 
 If you need a more sophisticated connection management, you can enable MessagingHub support which provides connection pooling
-and many other features. To enable MessagingHub add the following property to you application configuration:
+and many other features. To enable MessagingHub add the following dependency and property to you application configuration:
+```xml
+<dependency>
+    <groupId>org.messaginghub</groupId>
+    <artifactId>pooled-jms</artifactId>
+</dependency>
+```
 ```properties
 narayana.messaginghub.enabled=true
 ```
-All MessagingHub configuration properties described in its [documentation](https://github.com/messaginghub/pooled-jms/blob/master/pooled-jms-docs/Configuration.md) are mapped with a prefix `narayana.messaginghub`. So for example if you'd like to set an max connections pool size to 10, you could do that by adding this entry to your application configuration:
+
+All MessagingHub configuration properties described in its [documentation](https://github.com/messaginghub/pooled-jms/blob/master/pooled-jms-docs/Configuration.md)
+are mapped with a prefix `narayana.messaginghub`. So for example if you'd like to set a max connections pool size to 10,
+you could do that by adding this entry to your application configuration:
 ```properties
 narayana.messaginghub.maxConnections=10
 ```