Bug 780658 (SOA-3097)

Summary: QE Review: SOA Services Guide
Product: [JBoss] JBoss Enterprise SOA Platform 5 Reporter: David Le Sage <dlesage>
Component: DocumentationAssignee: David Le Sage <dlesage>
Status: CLOSED NEXTRELEASE QA Contact:
Severity: high Docs Contact:
Priority: high    
Version: 5.2.0 GACC: ldimaggi, pmacik
Target Milestone: ---   
Target Release: 5.2.0 GA   
Hardware: Unspecified   
OS: Unspecified   
URL: http://jira.jboss.org/jira/browse/SOA-3097
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2011-11-14 16:58:57 UTC Type: Task
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Bug Depends On:    
Bug Blocks: 780698    

Description David Le Sage 2011-06-01 22:26:05 UTC
Affects: Documentation (Ref Guide, User Guide, etc.)
project_key: SOA

Len, please review the Services Guide.  Note that no content changed in the upstream this time.

http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5/html/ESB_Services_Guide/index.html

Comment 3 Len DiMaggio 2011-07-05 15:16:29 UTC
Parent: Added: SOA-3147


Comment 4 Len DiMaggio 2011-07-08 17:49:38 UTC
Deferring the review of this doc - given all the changes related to the jUDDI/registry section being removed

Comment 5 Pavel Macik 2011-08-11 13:47:47 UTC
The "quickstart" expression is not consistent across the document (there are all "quick start", "quick-start" or "quickstart" used).
The document should use the expression "quickstart" on all places.

I've found following issues:
 * 2.1:
    ** (typo) "not every quick starts can run" --> "not every quick start can run"
    
 * 2.1.1 (before Figure 2.1)
   ** Figure 2.1 is "low resolution" and doesn't look good; it should be better.
   ** "Service registry" section - the last sentence refers to "ESB Services Guide"... this is an "ESB Service Guide" but there is no registry section in this document... maybe It should refer to "JUDDI Registry Guide"?

 * 4.2.2
   ** 3rd example configuration Note is doubled...
   ** 6th example table borders are not rendered in the PDF. There is only the text left.

 * 4.2.3
   ** Example MVEL Expression table borders are not rendered in the PDF. There is only the text left.

 * 4.2.4
   ** (typo?) "For this code snippet to be work,..." --> "For this code snippet to work,..."
   ** the paragraph beginning by "If you want your implementation to be configured..." is out of the page borders in the PDF (p.16).

 * 4.2.5
   ** the quick start layout figure is broken and it doesn't reflect the current quick start's ESB archive content...

 * 5.1.2
   ** (typo) 6th paragraph: "...interesting information, packageg it..." --> "...interesting information, package it..."

 * 5.2.1
   ** (typo) "This provider is very easy to use and supports both inline and external rule definitions." --> "This provider is very easy to use and supports both in-line and external rule definitions."

 * 5.4.4.2
   ** the jboss-esb.xml file content is not well-formatted 

 * 5.4.4.4
   ** Notes reference JBoss Rules manual/Guide... there is only "JBoss Rules 5 Reference Guide" in the SOA-P document suite and there is neither "Rule Agent section" nor "how to install BRMS" in that document.

 * 6 
   ** (typo) Smooks section: "...target data formats, including XML, EID, CSV and Java..." --> "...target data formats, including XML, EDI, CSV and Java..."
   ** 2nd Note: The "JBoss SOA Platform Programmer's Guide" is actually named "ESB Programmers Guide".

 * 7.2 
   ** The jbpm.esb/jbpm-service.xml file's content snippet doesn't match the actual file content. In the actual file the "classpath" elements are not present and the "jboss.esb:service=JbpmService" mbean section is quite longer.
   ** Warnings: the Hypersonic and H2 is switched. In fact jbpm-ds uses H2 database and the second Warning should refer to Hypersonic instead of H2.
   ** 1st paragraph after Note: the "It" in the second sentence should not be bold formatted.
   ** 1st paragraph after Note: the web-based application's address should be "http://localhost:8080/jbpm-console".

 * 7.3 (typo) last Note: "...refer to the JBPM Guide." --> "...refer to the JBPM Reference Guide."

 * 7.6
   ** the section headline should be "JBPM-to-ESB Integration" to be consistent with other sections.
   ** first sentence: "JBPM-to-JBossESB communication..." --> "JBPM-to-ESB communication..."

 * 7.6.1
   ** bpmToEsbVars section: bpm and default list items should be bold formatted

 * 7.6.2
   ** Table 7.5 Sub-Elements: the default list item should be bold formatted

 * 7.6.3
   ** first paragraph: the process modelling docs address should be "http://docs.jboss.com/jbpm/v3.2/userguide/html_single/#processmodelling"

 * 7.6.4
   ** first paragraph refers to a "diagram below". It is not a diagram but a "process definition snippet".

 * 8.3
   ** procedure 8.1: the code snippets in steps 13, 14, 16, 17, 21 and 22 should be better formatted (xml element indentation).

 * 8.4
   ** procedure 8.2: the code snippets should be better formatted (xml element indentation).


Comment 6 Pavel Macik 2011-08-12 07:29:21 UTC
 * 7
  ** All occurences of "m-bean" in the whole section 7 should be replaced by "MBean"
 * 7.4
  ** The paragraph following the Warning is out of the page borders in the PDF


Comment 7 Pavel Macik 2011-08-12 11:26:27 UTC
 * 6
  ** ActionProcessor list item: ActionProcessor class is deprecated - it has been replaced by ActionPipelineProcessor, so the section should be updated accordingly.

Comment 8 Pavel Macik 2011-08-12 14:31:51 UTC
 * 2.1.1
  ** (typo) 2nd step of the procedure 2.1: the right file path is "SOA_ROOT/samples/quickstarts/conf/quickstarts.properties"
 * 4.1.1
  ** (typo): "The rule service functionality is provided by the BusinessRuleProcessor and ..." --> "The rule service functionality is provided by the BusinessRulesProcessor and ..."
  ** (typo): "The BusinessRuleProcessor class allows ..." --> "The BusinessRulesProcessor class allows ..."
  ** (typo): "... multiple rule files for a single BusinessRuleProcessor action." --> "... multiple rule files for a single BusinessRulesProcessor action."

Comment 10 Len DiMaggio 2011-11-14 16:58:57 UTC
Closing - QE doc reviews are complete.