Bug 778576 (SOA-1048)

sections 14.6 & 14.7 fixed.

column widths of tables 5.1, 5.2, 5.3, 5.4, 5.5 fixed.

table 18.1 -> 18.29 are fine

Assigning to QE for review

Reopening and reassigning to Darrin. Review comments will come in the next JIRA comment.

General comments:

0) Very good job technically, I found no factual errors in the text. The language on the other hand... :-(
1) Capitalization issues - please make sure that the following words use capital letters where appropriate: Java, jBPM, JBoss, jPDL, XML, Hibernate, Eclipse, Petri net, JNDI, JDBC, XA, LDAP, Ant, Xerces... This occurs on so many places that I suggest mass search&replace.
2) Most of the diagrams in the document have a very low picture resolution / compression issues, making them look ugly. I suggest taking a look at the printout.
3) Things like "graph based," "domain specific" or "process oriented" should actually go by "graph-based," "domain-specific" and "process-oriented." Occurrences of this phenomena are too many to mention.
4) Pretty pretty please, get native English proof-reader - I'm sure I missed quite a lot of grammar-related problems.
5) Please mass replace all the "till"s with "until" and also check if "cause" (based on the context) cannot be replaced for "because."
6) The actual spelling of "particular" is with "a" not "e" (as in "perticular"). Another mass replace, please.
7) I think using "web application" instead of "webapp" would help. Another mass replace.
8) Double colons (and question marks) aren't AFAIK usually preceded by spaces. Many occurrences in the document where they are.
9) Starter's kit is sometimes referred to as "starters-kit" - it'd be cool to unify this.
10) Most of "-ful" words like powerful, handful etc. are actually written with just a single "l" at the end. Occurences are quite a few, perhaps RE could be made to fix that.
11) "Whether" isn't "wether," another candidate for mass replace.
12) "more then" can be mass-replaced with "more than."
13) It's not "ommited" or "ommitted," it's just "omitted."

Page by page: (P${pageNumber}, ${chapterNumber})

P1, 1: "... process language is buil*t* on top..."
P1, 1.2: First sentence contains "Download" 3 times.
P3, 1.5: 
- "EJB will be writen against" - isn't it written already? Or should it be written by the user?
- "We have done great efforts ..." - AFAIK efforts aren't done but taken.
P3, 1.6: "... is richer th*a*n the traditional..." (This problem actually occurs in quite some places.)
P7, 3:
- "The examples can also be fo*u*nd..."
- "download jbpm-3.0-[version].zip" - please highlight the file name based on the document conventions, including highlighting the "[version]" in italics. (repeats on P144, 18.1.2.)
- Last paragraph is actually an unfinished sentence that appears out of place.
P7, 3.1: "The hello world process" - it would be good to highlight "hello world" to indicate that it is some identifier.
P9, 3.2: "E.g. a*n* piece" - the "n" shouldn't be there, should it?
P20, 4.1.1: 
- "The IDE is buil*t* around..." - another very common mistake throughout the text.
- "When a user saves*,* the compiled class is saved*.*" - May I suggest better use of interpunction?
- "Where ten years ago..." - The sentence doesn't make much sense to me by itself. Either remove the "where" or join it with the other sentences in the paragraph somehow.
- "... is a common foundation for all these type*s* of domain*-*specific..."
- "... to edit *J*ava in the *source* file format*, because* ..."
P21, 4.1.2.1: 
- "An imperative programming language*s* like..."
- "... implementation technique is only targets..."  - please remove the "is"
- "... of the order manager and the*n* wait *until*..."
- "This could be a sufficient..." - please remove the " a"
P22, 4.2.1: "nodes have leaving*-* and arriving..." - please remove the dash.
P25, 4.2.3: "The event method will propagate find..." - please choose only one verb. :-)
P26, 4.2.3: "... doubleCheck's task node is adds ..." - the same as immediately above :-)
P27, 4.2.5: "... an event is sen*t* to the execution."
P29, 4.3.2: 
- "... mixed up with multi-threaded* *programming."
- "... in the process execution relate*s* ..." - please remove the "s".
P30, 4.3.3: "... An invoke will start *of* a new sub process." - Please remove the "of".
P30, 4.3.4: "Messaging systems are also know*n* as..."
P33, 4.5.1.1: "Let's define a business process" should IMHO be quoted.
P35, 4.5.2: "... for writing *a* new services..." - please remove the "a"
P36, 4.6: "... even the BPM engine's database tables *in* integrated into..." - please remove the "in"
P37, 4.7.2: 
- "This is problematic because it results in monolithic system that is very hard to integrate into a project *SOMETHING MISSING* combines plain OOP software with business processes."
- "... with the BPM server *to* become..." - please remove "to"
- "As show*n* above, ..."
P38, 4.7.3: I suggest either filling the chapter with content or removing entirely.
P39, 5: "... project, rather th*a*n installing..."
P40, 5.3: "Only used in the script's and decision's..." - please remove the apostrophes.
P41, 5.5: 
- "JobListenerBean - a Message*-*Driven Bean that listen*s* on the..."
- "Note however that jBPM only provide*s* deployment..." - also, the whole sentence would look better in a "Note" environment.
- "The javadocs ** in ..." - perhaps "are" is missing or something...
P43, 5.5: "jbpm.cfg.xml include*s* the following..."
P48, 6:
- "Typically,  you make a copy the default configuration..." - doesn't make much sense.
- "The third part are some misc*a*llanious configurations..."
P50, 6.3: The whole chapter would look much better in a bullet-point list instead of naming every config file in its own subchapter with one sentence in it.
P51, 6.3.7: "The id*'*s are stored..." - please remove the apostrophe.
P51, 6.5: "Therefor*e*, by default, the ... *the that* *H*ibernate" - please add "e", remove "the" and make Hibernate use capital "H."
P55, 7.1.1: "The persistence API *is integrated with*..."
P58, 7.1.2: "As a result, a Hibernate session will *only be opened*"...
P59, 7.1.3: 
- "The transaction attribute..." - please end the sentence with a full stop. Even better, put it in some other paragraph, as it's just one sentence.
- The following sentence begins with "the the".
P60, 7.2.1:
- first paragraph: names of the properties should be highlighted.
- seconds paragraph: we have an environment for important notes.
P62, 7.3: "and use the session per transaction pattern" - please, either put the "session per transaction" in quotes or join it using dashes.
P65, 7.6.3: 
- "The jbpm.db subproject*,* contains..." - please remove
- "... scripts for all database*s*..."
P65, 7.7:
- "This can eliminate*s* ..." - please remove
- Secondly, this enable*s* ..."
P66, 7.8: The bullet-point list should either state sentences (first letter capital, last letter followed by a full-stop) or the first two bullet points should end with a comma (",") and the last one with a full-stop.
P70, 8.1.3: "... only takes a few minutes in *windows*." - I suggest we either use full name and state whose trademark is that, or we stop using our competitors' products in examples... :-)
P72, 8.1.4.1: "*To execution* this script..." - doesn't seem right.
P74, 8.1.4.2:
- "mysql -u root -p" - the username should be in italic as it depends on an environment. Also, once we do this, most of the next paragraph can be left out.
- "Once the script executes, you should have the foll*ow*ing..."
P76, 8.1.6: "Well, almost..." - I'd follow that with a line break.
P77, 8.1.6: "This section should look like shown in the listing below. There are
two changes in this file: the hibernate.connection.datasource property should point to the JbpmDS
datasource we created as the first step in this section and the hibernate.dialect property should match
the PostgreSQL or MySQL dialect." - properties should be highlighted.
P82: "You may have to ALT-TAB to get this application as it may be covered by another window." - I suggest we don't treat jBPM users as idiots who don't know anything about window management. :-) And if we do, Alt+Tab is heavily dependent on user's environment, so I'd left that out.
P88, 9.3.4:
- The first paragraph would be much better when converted into a bullet-point list with two items.
- Also, "Should the decision made by the process..." doesn't make much sense.
- "The first paragraph for which the *conditions resolves* to 'true'"... you can't have both words ending with "s" in this case.
P89, 9.4: "If more th*a*n..."
P93, 9.6.2: "... to distinct between..." - is "distinct" a verb?
P94, 9.7: s/serached/searched
P97, 9.10: s/implementated/implemented
P101, 10.1: "The most basic operations are*:*"
P102, 10.4.1: s/independant/independent
P103, 10.6: "hibernatable type" - really? :-) (Two occurences.)
P104, 10.6: "When you refer *to* your custom..."
P105, 10.6 type "LongInstance" should be highlighted.
P108, 11.2.2: "... one task instance *are* associated..."
P110, fig 11.1: Instances' arrows go into the boxes.
P110, 11.3.4: "*T*o specify the pooled actors..."
P111, 11.4: "The controller can be used to create*,* populate and ..."
P111, 11.5: Please remove the a) and b) from the bullet-point list.
P113, 11.6: s/assignements/assignments
P119, 12: 
- "IMPORTANT NOTE": We have an environment for that, don't we?
- In the same paragraph, the repository method should be highlighted.
- Same comment for the bullet-point list as in "P66, 7.8"
- "a word document" - either use the full trademark name of Microsoft Word or don't mention the product at all. :-)
P121, 13.1: 
- "A timer that is specified on a node*,* is not executed" - without the comma, please.
- Same comment for the bullet-point list as in "P66, 7.8"
P123, 14.2: 
- "... by looking *at* two examples."
- "The first frame*,* show the..." - without the comma, please.
P124, 14.2: "Now, we are going to look at the second example, the second example is a variant..." - I smell redundancy...
P125, 14.2: "2 separate transactions*, o*ne transaction each part."
P127, 14.4: 
- "... messages will be sen*t* by..."
- "... looks like this: " - the following list of items would IMHO look much better if it were an actual list.
P128, 14.4: 
- "If for *one* reason or another..."
- "Limitation: " - this would look better in some sort of Note/Warning environment.
P128, 14.6: "... as asynchronous *w*as well as produce..." - remove the "w"
P129, 15.1:
- "As mentioned*,* the due date..."
- "... calculating the due* *date."
P129, 15.1.1: "Double.parseDouble(quantity)" - highlight, please.
P129, 15.1.2:
- "JbmException" - highlight, please.
- NOTE should actually become a Note.
P133, 16.1.1:
- "... resolved to email addresses with by means..." - remove "with", please.
- The next paragraph should end with a full-stop.
P134, 16.1.3:
- "... can be sen*t*..."
- "Setting notify to yes, true or on will..." - please highlight the values.
P134, 16.2: please end the first paragraph with a full-stop.
P135, 16.3.2: "actorId*'*s" - please remove the apostrophe.
P139, 17:
- "delta's" - please remove the apostrophe (2 times)
- "... much time is spen*t* on..."
- "(wow, that a lot of seq's there :-s )." - please, remove entirely.
P141, 17.3: s/ordered/order
P141, 17.4: s/queryies/queries
P143, 18.1.1:
- s/cfg is optional/optional
- s/properties is optional/optional
- "hibernate.cfg.xml" - please, highlight.
P144, 18.1.4: "... for which there *are* not yet" - replace with "is"
P145, 18.1.5: The java command should be highlighted, indirectory and outdirectory in italics. If made so, the following paragraph is probably not needed.
P148: "Thanks Gavin! Absolutely awesome! :-)" - I suggest removal. (Nothing against Gavin, just that this note is IMHO inappropriate in customer-facing documentation. :-))
P167, 20.3: Either extend or remove, please.

The following items from the comment above are those that will not be able to be corrected due to time constraints & will be included in the next CP

P48, 6:
- "Typically, you make a copy the default configuration..." - doesn't make much sense.
- "The third part are some misc*a*llanious configurations..."
P50, 6.3: The whole chapter would look much better in a bullet-point list instead of naming every config file in its own subchapter with one sentence in it.
P51, 6.3.7: "The id*'*s are stored..." - please remove the apostrophe.
P51, 6.5: "Therefor*e*, by default, the ... *the that* *H*ibernate" - please add "e", remove "the" and make Hibernate use capital "H."
P55, 7.1.1: "The persistence API *is integrated with*..."
P58, 7.1.2: "As a result, a Hibernate session will *only be opened*"...
P59, 7.1.3:
- "The transaction attribute..." - please end the sentence with a full stop. Even better, put it in some other paragraph, as it's just one sentence.
- The following sentence begins with "the the".
P60, 7.2.1:
- first paragraph: names of the properties should be highlighted.
- seconds paragraph: we have an environment for important notes.
P62, 7.3: "and use the session per transaction pattern" - please, either put the "session per transaction" in quotes or join it using dashes.
P65, 7.6.3:
- "The jbpm.db subproject*,* contains..." - please remove
- "... scripts for all database*s*..."
P65, 7.7:
- "This can eliminate*s* ..." - please remove
- Secondly, this enable*s* ..."
P66, 7.8: The bullet-point list should either state sentences (first letter capital, last letter followed by a full-stop) or the first two bullet points should end with a comma (",") and the last one with a full-stop.
P70, 8.1.3: "... only takes a few minutes in *windows*." - I suggest we either use full name and state whose trademark is that, or we stop using our competitors' products in examples... :-)
P72, 8.1.4.1: "*To execution* this script..." - doesn't seem right.
P74, 8.1.4.2:
- "mysql -u root -p" - the username should be in italic as it depends on an environment. Also, once we do this, most of the next paragraph can be left out.
- "Once the script executes, you should have the foll*ow*ing..."
P76, 8.1.6: "Well, almost..." - I'd follow that with a line break.
P77, 8.1.6: "This section should look like shown in the listing below. There are
two changes in this file: the hibernate.connection.datasource property should point to the JbpmDS
datasource we created as the first step in this section and the hibernate.dialect property should match
the PostgreSQL or MySQL dialect." - properties should be highlighted.
P82: "You may have to ALT-TAB to get this application as it may be covered by another window." - I suggest we don't treat jBPM users as idiots who don't know anything about window management. :-) And if we do, Alt+Tab is heavily dependent on user's environment, so I'd left that out.
P88, 9.3.4:
- The first paragraph would be much better when converted into a bullet-point list with two items.
- Also, "Should the decision made by the process..." doesn't make much sense.
- "The first paragraph for which the *conditions resolves* to 'true'"... you can't have both words ending with "s" in this case.
P89, 9.4: "If more th*a*n..."
P93, 9.6.2: "... to distinct between..." - is "distinct" a verb?
P94, 9.7: s/serached/searched
P97, 9.10: s/implementated/implemented
P101, 10.1: "The most basic operations are*:*"
P102, 10.4.1: s/independant/independent
P103, 10.6: "hibernatable type" - really? :-) (Two occurences.)
P104, 10.6: "When you refer *to* your custom..."
P105, 10.6 type "LongInstance" should be highlighted.
P108, 11.2.2: "... one task instance *are* associated..."
P110, fig 11.1: Instances' arrows go into the boxes.
P110, 11.3.4: "*T*o specify the pooled actors..."
P111, 11.4: "The controller can be used to create*,* populate and ..."
P111, 11.5: Please remove the a) and b) from the bullet-point list.
P113, 11.6: s/assignements/assignments
P119, 12:
- "IMPORTANT NOTE": We have an environment for that, don't we?
- In the same paragraph, the repository method should be highlighted.
- Same comment for the bullet-point list as in "P66, 7.8"
- "a word document" - either use the full trademark name of Microsoft Word or don't mention the product at all. :-)
P121, 13.1:
- "A timer that is specified on a node*,* is not executed" - without the comma, please.
- Same comment for the bullet-point list as in "P66, 7.8"
P123, 14.2:
- "... by looking *at* two examples."
- "The first frame*,* show the..." - without the comma, please.
P124, 14.2: "Now, we are going to look at the second example, the second example is a variant..." - I smell redundancy...
P125, 14.2: "2 separate transactions*, o*ne transaction each part."
P127, 14.4:
- "... messages will be sen*t* by..."
- "... looks like this: " - the following list of items would IMHO look much better if it were an actual list.
P128, 14.4:
- "If for *one* reason or another..."
- "Limitation: " - this would look better in some sort of Note/Warning environment.
P128, 14.6: "... as asynchronous *w*as well as produce..." - remove the "w"
P129, 15.1:
- "As mentioned*,* the due date..."
- "... calculating the due* *date."
P129, 15.1.1: "Double.parseDouble(quantity)" - highlight, please.
P129, 15.1.2:
- "JbmException" - highlight, please.
- NOTE should actually become a Note.
P133, 16.1.1:
- "... resolved to email addresses with by means..." - remove "with", please.
- The next paragraph should end with a full-stop.
P134, 16.1.3:
- "... can be sen*t*..."
- "Setting notify to yes, true or on will..." - please highlight the values.
P134, 16.2: please end the first paragraph with a full-stop.
P135, 16.3.2: "actorId*'*s" - please remove the apostrophe.
P139, 17:
- "delta's" - please remove the apostrophe (2 times)
- "... much time is spen*t* on..."
P141, 17.3: s/ordered/order
P141, 17.4: s/queryies/queries
P143, 18.1.1:
- s/cfg is optional/optional
- s/properties is optional/optional
- "hibernate.cfg.xml" - please, highlight.
P144, 18.1.4: "... for which there *are* not yet" - replace with "is"
P145, 18.1.5: The java command should be highlighted, indirectory and outdirectory in italics. If made so, the following paragraph is probably not needed.

Regards the image quality problems: differing DPI in the source images to that of the rendered PDF cause a lot of the problems, this will be fixed to some degree in future versions.

BTW you did an awesome job, we are going to try to get as much as possible back into the jBPM source docs.  Thanks.

fixes applied up to and including chapter 5.
and 
- "(wow, that a lot of seq's there :-s )." - please, remove entirely. 
- P167, 20.3: Either extend or remove, please. 
- P148: "Thanks Gavin! Absolutely awesome! :-)" - I suggest removal

1st 13 items applied as well, except 2 which will be worked on for a future version

Please, file another issue for another release that would contain the remaining problems - then this can be closed.

Re-assigning so that my previous comment can be taken properly into account. :-)

SOA-1124 created for 4.2.CP04

Alright, closing.

Link: Added: This issue related SOA-1172