Community
Participate
Working Groups
Create COSMOS User's Guide for GA. Output: HTML, PDF and online helps. Approver: Mark Weitzel
*** Bug 215871 has been marked as a duplicate of this bug. ***
Reassigning to me as a placeholder.
Moving all open bugzillas that are targeted to iterations in the past to the next iteration (i13).
HTML files for users guide have been checked in to org.eclipse.cosmos/doc/vi12/usersguide/html . PDF and online help files were already there. Should this be marked as fixed?
Feedback for User Guide: In page "06" at the bottom there is the following sentence: "See the section Service Modeling Language Tooling and Usage for more information about tooling." I would change that to "...about the SML support provided by COSMOS." In "cosmosuserguide09.htm", it's a bit misleading listing all of that as prerequisites, since a lot of it is already included with COSMOS, such as the schemas and WSDLs. Also, I believe we removed things like ANTLR and Drools from our prereqs long ago (I think those two were SDD prereqs only). Right, Jason? Also Muse is no longer a prereq. The best source for listing our prereqs is the COSMOS IP Log, as it has been pruned to the correct list. Under Axis2, you can either refer them to the list in the install guide, list all the required libraries again here, or simply say "A subset of the Axis2 libraries is required for COSMOS operation". In "cosmosuserguide09C.htm", shouldn't it be spelled "Kernel" not "Kernal"? In "cosmosuserguide13", I'm not sure what is intended at the bottom, but the last two lines appear in Firefox in a typewriter font with some unresolved characters such as "<&cursor." In "cosmosuserguide14", the two missing chapters referenced in the dev guide were collapsed into one at one point. It's the 2nd chapter in the dev guide that both can reference, whatever that is called now. In "cosmosuserguide16", the word "describes" should be "described" in the 2nd sentence. In "cosmosuserguide18", the link to the SML spec should be changed to http://www.w3.org/TR/sml/. Also, please change the bullet right above that link to "Conforms to the SML-IF and SML specifications, version 1.1". And two bullets above that, please change to "Conforms to ISO Schematron rules bound to documents" The 3rd and 4th links under "SML Resources", should have their versions bumped as follows: # W3C SML Version 1.1 submission # W3C SML Interchange Format Version 1.1 submission And should be linked to: http://www.w3.org/TR/sml/ http://www.w3.org/TR/sml-if/ In "cosmosuserguide24", remove the example at the bottom. It's out of date, and really doesn't add much value. In "cosmosuserguide28", the "Install Software" PDF is probably the precursor to the install guide as we know it today. He is trying to refer to wherever we describe setup for the demo. Regarding the example, let's hold off for now since we might be allowed to at least refer to Tomcat as an example, pending the Eclipse legal discussion going on. Hopefully we'll have this resolved by midweek next week. Seeing that does make me realize our demo installation script still refers to and uses Tomcat to install itself. :-/
Sorry, I hit submit too quickly. Here are a few more: In "cosmosuserguide33" and the pages that follow, where it says "Need more information.", you will need to get someone like Srinivas, Jimmy, or JT to write that content. In "cosmosuserguide38", did we agree we would keep live links to the wiki? All those links refer back to the wiki for documenting the tutorials. In the Index, there are a few funny looking names like "web components250)" and "web console)" that need cleaning up. Everyone else, please give this a thorough review. I undoubtedly missed some things, esp. in the areas I don't know as much about.
(In reply to your edits:) In "cosmosuserguide09.htm", it's a bit misleading listing all of that as prerequisites, since a lot of it is already included with COSMOS, such as the schemas and WSDLs. I copied the table of prereqs from the Install Guide to this guide. If that’s not correct, please provide exact corrections. ---------------- In "cosmosuserguide13", I'm not sure what is intended at the bottom, but the last two lines appear in Firefox in a typewriter font with some unresolved characters such as "<&cursor." Changed last two lines to: The Client application invokes the Query Service of a federated configuration management database, which aggregates the results of the Query Service of one or more MDRs. Client Application <Query Service> CMDBf <Query Service> MDR CMDBf <Registration Service> MDR If that’s not correct, send specific changes. ---------------- In "cosmosuserguide16", the word "describes" should be "described" in the 2nd sentence. Not seeing this? ----------------- In "cosmosuserguide38", did we agree we would keep live links to the wiki? All those links refer back to the wiki for documenting the tutorials. I assume the group will chime in on this one.
(In reply to comment #7) > In "cosmosuserguide09.htm", it's a bit misleading listing all of that as > prerequisites, since a lot of it is already included with COSMOS, such as the > schemas and WSDLs. > > I copied the table of prereqs from the Install Guide to this guide. If that’s > not correct, please provide exact corrections. > ---------------- In my copy of the install guide, the prereqs list is shorter (cosmosprereqs.html). Several of the items you have aren't listed on that page. Specifically the items from SML/SML-IF schema files through service metadata schema can be removed, as they are prereqs that are shipped with COSMOS. Or, you could leave them there, but indicate that they do not need to install those themselves, as they are bundled with COSMOS. > In "cosmosuserguide13", I'm not sure what is intended at the bottom, but the > last two lines appear in Firefox in a typewriter font with some unresolved > characters such as "<&cursor." > > Changed last two lines to: > The Client application invokes the Query Service of a federated configuration > management database, which aggregates the results of the Query Service of one > or more MDRs. > Client Application <Query Service> CMDBf <Query Service> MDR > CMDBf <Registration Service> MDR > > If that’s not correct, send specific changes. Looks better, even though I don't know what was originally intended by that text. > In "cosmosuserguide16", the word "describes" should be "described" in the 2nd > sentence. > > Not seeing this? > ----------------- Look at the sentence starting with "COSMOS does offer special handling...". After the semicolon, it says "this is describes in the...", which is a grammatical error.
(In reply to comment #8) > In my copy of the install guide, the prereqs list is shorter > (cosmosprereqs.html). Several of the items you have aren't listed on that > page. Specifically the items from SML/SML-IF schema files through service > metadata schema can be removed, as they are prereqs that are shipped with > COSMOS. Or, you could leave them there, but indicate that they do not need to > install those themselves, as they are bundled with COSMOS. Sorry, I wasn't clear here: I meant I had copied the Prereq table from the Install Guide to the User Guide *after* reading this comment. So both guides have the same Prereq table, which I believe is now correct (save the Axis2 link issue, which we're waiting for Ruth's feedback on). > > Client Application <Query Service> CMDBf <Query Service> MDR > > CMDBf <Registration Service> MDR > > > > If that’s not correct, send specific changes. > Looks better, even though I don't know what was originally intended by that > text. I haven't received any other feedback on these last two lines. Should I keep them in at this point, or remove them?
(In reply to comment #9) > > > Client Application <Query Service> CMDBf <Query Service> MDR > > > CMDBf <Registration Service> MDR > > > > > > If that’s not correct, send specific changes. > > Looks better, even though I don't know what was originally intended by that > > text. > > I haven't received any other feedback on these last two lines. Should I keep > them in at this point, or remove them? I guess keep them for now, since I suppose there was some intent there. I'm hopeful that the author of those lines will comment so some clarification can be added.
There should be a copyright statement on page 1 of the user's guide like there is on page 1 of the dev guide
(In reply to comment #11) > There should be a copyright statement on page 1 of the user's guide like there > is on page 1 of the dev guide The Dev Guide has the copyright statement on the first page, as well as in a separate Appendix. I don't think this is necessary in both places (it's the exact same text); I'll pull the Appendix and just keep it on the cover. I'll also add that copyright info on page one of the User and Install Guides, so all guides are consistent.
Created attachment 116637 [details] User's Guide
Final version attached.
Across the three guides there were some orphan files, some broken anchors, and some missing ibmdita.css. (I forget which changes that I made to which files.) Checked in now into CVS and into the web site.
