Documentation needs revision as a result of review

The following comments are relevant to the work-in-progress version of the EAP 5.2.0 Administration and Configuration Guide.

As a starting point, the following is the URL for the first section in Chapter 18. Pooling:
http://documentation-devel.engineering.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html-single/Administration_And_Configuration_Guide/index.html#idm104551576

Section 18.1 Strategy
(1) The 'Note' admontion needs to be reworded: "The xml names imply this is just about security. This is misleading." It needs to clarify just what the XML names DO imply, not just state what they *DON'T imply. In other words, this need to be a positive, not negative statement;
(2) In the same admonition, "xml" should be "XML";
(3) In the text following the admonition: "For <security-domain-and-application/> the Subject always overrides any user/password from createConnection(user, password) in the CRI:", "Subject" should be marked up to differentiate it from the standard English-language word.

Section 18.2 Workaround for Oracle
(1) "Oracle does not like XA connections..." This needs to be reworded to remove the word "like". Human aspects should not be applied to non-human entities;
(2) "Oracle" needs to be clarified in the section's title and text. Is "Oracle" referring to the company, the JDK distributed by Oracle, or something else entirely?

Section 18.3 Pool Access
(1) "Upto <max-pool-size/>...". "Upto" should be "Up to";
(2) "Once this limit is reached, threads wait for the <blocking-timeout-seconds/> to use the pool before throwing a No Managed Connections Available". (2a) "...threads wait for the..." should be reworded, perhaps something like "...threads wait for the <.../> period..". (2b) "...throwing a No Managed Connections Available"...what? It needs to be clear that "No Managed..." is an exception;
(3) "You may want to use the..." needs to be reworded to avoid "...may want to...".

Section 18.4 "Pool Filling"
(1) "<prefill/> - Feature Request has been implemented for 4.0.5. Note: the only pooling strategy that supports this feature is OnePool?, or ByNothing? pooling criteria." "The presence of 'Feature Request' looks like this text might have been an internal comment which has not been properly edited. Please review the text and edit it. The presence of "OnePool?" and "ByNothing?" also looks strange;
(2) In the admonition I suggest that "min-pool-size" needs to be marked up as a parameter.

Section 18.5 Idle Connections
(1) Paragraph 1 features "This is done via the <idle-timeout-minutes/>." "...via the <.../>" what? Perhaps this needs only "... parameter" added to the end of the sentence;
(2) Paragraph 2 features "The check is done every idle-timeout-minutes divided by 2 for connections unused for idle-timeout-minutes." (2a) The parameter 'idle-timeout-minutes' needs to be marked up as a parameter. (2b) The mathematical formula in this sentence is not marked up at all so it's not clear. Please review this and perhaps present the formula differently;
(3) Paragraph 3 features "Should closing idle connections cause the pool to fall below the min-pool-size...". "...min-pool-size" needs to be marked up as a parameter and it needs "...parameter" added to the end of the sentence;
(4) The admonition features "If you have long running transactions...". "long running" should be "long-running".

Section 18.6.1 Valid connection checking
(1) (1a) The sentence beginning "The simplest format is to just run a "quick" sql statement:" is split and needs to be reworded. (1b) In the same sentence, the word "just" needs to be removed. (1c) "sql" should be "SQL";
(2) "...e.g. Oracle's or MySQL's pingDatabase() via the". This sentence needs to be completed before referring to the parameter.

Section 18.6.2. Errors during SQL queries
(1) "You can check if a connection broke during a query by the looking the error codes or messages of the SQLException for FATAL errors rather than normal SQLExceptions. (1a) "...looking the error codes..." needs to be reworded. At a minimum it's missing the word "at". I'd suggest something like "checking the error codes". (1b) "FATAL" should be marked up.

Sections 18.6.3. Changing/Closing/Flushing the pool and 18.6.4. Other pooling
Both sections make direct reference to the JBoss wiki, but without any introductory text to link what's mentioned in the "Administration and Configuration Guide" with the wiki's content. Either these links need to be removed or the relevant content from the wiki need to be merged into the guide.

Chapter 19. Frequently Asked Questions is worthless IMHO. It lists only one question yet the text of the answer then lists several further questions. The text of the only "Question" and associated answer has clearly been cut-and-pasted from another source. The reader is prompted to read this section if they have had problems with Oracle XA but there is no mention of the symptoms for which the reader should refer to this section. Halfway through the text is "Configuring Oracle Database for XA Support" which looks like it should be the start of a new section but is not marked up as such. Please review this entire chapter and the official IBM documentation referred to by it and either rewrite it or delete it.