Hide Forgot
Date of First Response: 2008-10-16 19:43:34 project_key: SOA Let's collect all comments for Darrin for the ./docs/esb/Getting_Started_Guide.pdf in this JIRA
A few observations and suggestions: 1.Pg 1, JDK table. Format so table is on one page 2.Pg 3 Migrating ESB. Migration issues are mentioned, but are they API differences? Is there anyway we can point to a document that points out the differences instead of saying, Hey customer, you have to find out yourself... 3.Example commands are given in "Linux", but I could not find any comment about that in the preface. Sometimes there is only Linux version of command, sometimes Windows and Linux... 4.Pg 10 sect. 3.3 sentence says ...decorated messages payloads... I can't make sense of that, to me, it is incorrect grammar. 5.Pg 10 sect. 3.3 last paragraph. The initial sentence should be re-written to be clearer. 6.Pg 11 sect.3.4. Shouldn't "run in every deployment" say "run in any configuration", since deployed often means put in production? /Anne-Louise
We also have to describe how a user deploys a new .esb through the console.
1 - unfortunately I don't have a lot of control over final formatting, I just just dictate the structure. So I can't stick a page-break or extra line feed or anything like that. It does bug me too, I'll have to either add a few more lines of content before it to push it down to the next page or remove 5 or 6 lines. 2 - I agree. Can anyone point me to this material. It's really a bit late to include more material at this stage, but it would be good for FP01 3 - Yeah there is a lot of inconsistency with the commands. I think I'll log a specific JIRA for cleaning those up. 4 - Eww. Bad wording. Its referring to the payloads of decorated messages. How about: "This construct makes it possible to easily pass the payloads of compliant messages between components of the JBoss SOA Platform." 5 - which sentance are you referring to? 6 - I'd say 'deployed' just means "put on your server", whether that's production, QA or a dev server on your laptop. I see your point though & will think about the phrasing. Actually it would be nice to have an offical glossary for terms like this.
"We also have to describe how a user deploys a new .esb through the console. " That probably belongs in the Administration Guide, not the Getting Started Guide.
fixed up the OS specific commands.
6 - updated to "Not all the Quickstarts will run on every server configuration."
reformatted some content to force the JVM requirements table onto the next page ;-) that just leaves #5
Security: Added: Public
JIRA moved from https://jira.jboss.org/jira/browse/JBQA-1899 to SOA-964.
#5 - helloworld quickstart content rewritten
Hey Darrin - too late for these comments - just saw them in the GA doc - do we ever post the docs on a website for download? Cover Page * A guide to the inital installation & configuration of the JBoss Enterprise SOA Platform. (initial) 1.1.1 * It is the developers' responsiblity to provide performance requirements for their own services & applications to be deployed. (responsibility) * The full installation of the SOA Platform server requires 600 megabytes of harddrive space. (hard drive) 1.1.2 * They are fully supported and compatiable implementations. (compatible) * Azul JDK 1.5.x (We never tested with this - EAP has, but not SOA-P - there may be issues with some of the platform s projects) 1.3 * Which you use will depend on your needs. (Wording - how about: The server you select will depend on your needs.) 2.1.1 * The scripts expect the platform to be in one of the configurations that the scripts provide. The scripts can be run again to change the configuration unless changes are made in addition to what the scripts provide. (I'm not sure what this is trying to say. Do we mean to tell the user that the scripts can only be used to modify an out-of-the-box configuration?) * You can perform the reconfiguration manually by typing ant while in the schema directory, or automatically by editing build.properties. (We never told the reader to install ant.) * Hypersonic SQL provides default database functionality for evaluation and development use only. It is not recommended or supported as a production-use database. (We never told the user that HSQL DB is configured by default.) * cp -rf default development (how about cp -rp - to preserve file permissions) 2.1.3.1 * In the embedded JBoss EAP version, the all profile has the development version of the war, and the production profile has the production version. (Both the all and the default profiles have the development version of the war.) 3.2.1 * This well defined concept of a message is often refered to as an ESB Message1. (referred)
Reopening so that Len's suggestions can be taken into account next time this document is spun.
incorporated fixes Added "installing Ant" section
Reference to installing ant - verified in doc here: https://svn.corp.jboss.com/repos/soa/branches/4.3/build-tools/docs/esb/