4 Replies Latest reply on Mar 17, 2009 7:39 AM by marklittle

    A guide on how to use... the guides!

    mauromol

      Hello,
      I was trying to organize JBoss Transactions documentation in order to know what I should print and read... but I'm realizing it's a mess!

      I mean, in jbossts-full-4.6.0.GA.zip I find a docs folder with:
      - a JBoss Transactions 4.6.0 Installation Guide
      - a JBoss Transactions 4.6.0 Administration Guide
      - a JBoss Transactions 4.6.0 JTS Programmers Guide
      - a JBoss Transactions 4.6.0 Quick Start Guide
      - a JBoss Transactions 4.6.0 Transaction Core Programmers Guide
      - a JBoss Transactions 4.6.0 Failure Recovery Guide
      - a JBoss Transactions API 4.6.0 Programmers Guide

      In jbossts-jta-4.6.0.GA.zip, instead, I find a docs folder with:
      - a JBoss Transactions API 4.6.0 Installation Guide
      - a JBoss Transactions API 4.6.0 Programmers Guide (same as above, I think)
      - a JBoss Transactions API 4.6.0 Administration Guide
      - a JBoss Transactions 4.6.0 Transaction Core Programmers Guide (same as above, I think)
      - a JBoss Transactions 4.6.0 Failure Recovery Guide (same as above, I think)

      The src packages (jbossts-full-4.6.0.GA-src.zip and jbossts-jta-4.6.0.GA-src.zip) seem to be quite more in order, because they distinguish between:
      - ArjunaCore
      - ArjunaJTA
      - ArjunaJTS (only in jbossts-full package)
      and all of them have their set of docs.

      I also find that a lot of the documentation is replicated in many of the docs (for instance, the Administration Guides are very similar to each other, with little differences...), while the ArjunaCore 4.6.0 Administration Guide is not present in any of the bin packages. This is driving me crazy, so could you please help me to know what should I read?

      In particular, my case is the following: I'm using jbossts-jta package to embed JBossTS into my web application. The transaction manager is configured and used through Spring. I need to start and stop the transaction manager and all the associated services (like the recovery manager) when the web application is started and stopped. I found that some documentation about this is in the ArjunaCore documentation, but it is not in the ArjunaJTA documentation.

      My questions are:
      - why ArjunaCore 4.6.0 Administration Guide is not in the binary package of jbossts-jta? There is some information I need there (on how to start and stop the transaction manager), which is not present in any of the other administration guides...
      - which Administration Guide(s) should I read? And in which order?
      - which Programmers Guide(s) should I read? And in which order?

      I also find that there are some information that may not be up-to-date in the installation guides: for instance, I can't find the scripts to start the Transaction Manager as a service under Windows, mentioned in the Installation Guides (there are just those to start the Recovery Manager as a service).

      Mauro.

        • 1. Re: A guide on how to use... the guides!
          marklittle

          Read everything in the docs release. It's all important! If it's duplicated then you can ignore it and save yourself some time. If you have specific queries then create separate discussion topics. We may then end up creating specific JIRAs if there are issues we need to fix.

          Some of the Core TM docs are probably of less use to you if you are purely interested in JTA. But Failure Recovery is something you cannot live without.

          • 2. Re: A guide on how to use... the guides!
            mauromol

             

            "mark.little@jboss.com" wrote:
            Read everything in the docs release. It's all important! If it's duplicated then you can ignore it and save yourself some time. If you have specific queries then create separate discussion topics. We may then end up creating specific JIRAs if there are issues we need to fix.

            Some of the Core TM docs are probably of less use to you if you are purely interested in JTA. But Failure Recovery is something you cannot live without.


            I feared you would have replied to "read everything"... However, still I can't understand the point.

            For instance, the ArjunaCore 4.6.0 Installation Guide and the JBoss Transactions API 4.6.0 Installation Guide at a first (and second...) glance are the EXACT SAME document where, in the latter the "ArjunaJTA" string replaces the "ArjunaCore" string of the former... So, what's their scope and/or target? I tried to read the "What this guide contains" and "Audience" sections of each guide, but they're of no help.

            For instance, in ArjunaCore 4.6.0 Installation Guide I read:

            What This Guide Contains
            The Installation Guide contains information on how to use ArjunaCore 4.6.0.

            Audience
            This guide is most relevant to engineers who are responsible for installing ArjunaCore 4.6.0 installations.

            In JBoss Transactions API 4.6.0 Installation Guide I read:

            What This Guide Contains
            The Installation Guide contains information on how to use JBoss Transactions API 4.6.0.

            Audience
            This guide is most relevant to engineers who are responsible for installing JBoss Transactions API 4.6.0 installations.

            So, apart from the fact that I think that these guides don't tell you how to "use" (rather than to "install") the library and that I can hardly realize how a Java library could be "installed", I really can't understand what is the difference between the two guides and who is the target audience of the two documents. If it's the same, how about writing an only document?

            Maybe I'm also lacking of some background knowledge on the relationships between the different JBoss Transactions components (core vs JTA vs JTS) regarding this topic (i.e.: installation), but this is something I thought I could find in the guides themselves...

            The installation case is just an example, but I would have similar questions about the administration guides, too...

            Mauro.

            • 3. Re: A guide on how to use... the guides!
              marklittle

              Believe it or not but not everyone wants to use JTA. Some people may only be interested in the Core engine, so those docs are relevant to them. I'm pretty sure I said you could ignore anything that seems to be duplicated ;-) Try this approach: start at the level you're interested in (JTA) and work down: anything that you come across that contradicts or duplicates what you've previously read then you can ignore.

              • 4. Re: A guide on how to use... the guides!
                marklittle

                BTW, as I also said, if you feel that there are issues in the docs (structure, content etc.) that need addressing then create some JIRAs. The worst that will happen is that they get ignored. The best is that they get addressed. Usually the latter approach wins out ;-)