Qpid
  1. Qpid
  2. QPID-2725

Large quantities of documentation are duplicated

    Details

    • Type: Bug Bug
    • Status: Resolved
    • Priority: Critical Critical
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Documentation
    • Labels:
      None

      Description

      The way we generated documentation has led us to duplicate a large amount of contents which will be hard to maintain.

      This is because we have the ability to make 1 Book that includes all the documentation yet still make individual books.
      The problem is in the 1 Book scenario we need to use the <part> tag for content and in the individual books we need <book>

      The simple solution is to have the individual book include the <part> but we are not doing that, we are duplicating the code and in some cases we have an IDENTICAL file checked in twice: Qpid-Book.xml and Book.xml I'm looking at you.
      These individual books all have the same code as the files that don't have the -Book
      src/AMQP-Messaging-Broker-CPP-Book.xml src/Qpid-Compatibility-And-Interoperability-Book.xml
      src/AMQP-Messaging-Broker-Java-Book.xml

      They need updated to import the non -Book version or we will end up with in consistent documentation.

        Activity

        Hide
        Martin Ritchie added a comment -

        Committed change for the src/AMQP-Messaging-Broker-Java-Book.xml to include the Java.xml but other items still need reviewed.

        Show
        Martin Ritchie added a comment - Committed change for the src/AMQP-Messaging-Broker-Java-Book.xml to include the Java.xml but other items still need reviewed.
        Hide
        Jonathan Robie added a comment -

        I've left some files here that I should remove, e.g. book.xml vs. Qpid-Book.xml.

        Most of the content here is simply a set of includes, with an introduction added. We have different ways of packaging the same includes.

        The Makefile uses only these top-level files:

        AMQP-Messaging-Broker-CPP-Book
        AMQP-Messaging-Broker-Java-Book
        Programming-In-Apache-Qpid

        > This is because we have the ability to make 1 Book that includes all the documentation yet still make individual books.
        > The problem is in the 1 Book scenario we need to use the <part> tag for content and in the individual books we need <book>
        >
        > The simple solution is to have the individual book include the <part> but we are not doing that

        Qpid-Book.xml contains everything in the individual books for the two brokers, plus an introductory section and appendices. Each of the brokers also has its own book. So Qpid-Book contains all of the contents of the other two books.

        Some of this other content never occurs in another book. In a book that describes just the C++ broker or just the Java broker, each has an introduction that explains that there are two implementations of the broker, and this particular book describes one of them. In the long run, the best solution would be to have the two brokers interop to the point that there are few differences, and one book could easily describe both of them, with a few sections that apply to just one or the other.

        It might make sense to reflect the docbook levels book, part, and section in our file names, that would make it easier to get an overview of how the files relate to the docbook structure. We currently have files at the book and section levels, but gloss over the fact that parts exist.

        Before doing any significant restructuring of the files, I'd like to have a clear direction on the structure we want for the documents per se going forward.

        Show
        Jonathan Robie added a comment - I've left some files here that I should remove, e.g. book.xml vs. Qpid-Book.xml. Most of the content here is simply a set of includes, with an introduction added. We have different ways of packaging the same includes. The Makefile uses only these top-level files: AMQP-Messaging-Broker-CPP-Book AMQP-Messaging-Broker-Java-Book Programming-In-Apache-Qpid > This is because we have the ability to make 1 Book that includes all the documentation yet still make individual books. > The problem is in the 1 Book scenario we need to use the <part> tag for content and in the individual books we need <book> > > The simple solution is to have the individual book include the <part> but we are not doing that Qpid-Book.xml contains everything in the individual books for the two brokers, plus an introductory section and appendices. Each of the brokers also has its own book. So Qpid-Book contains all of the contents of the other two books. Some of this other content never occurs in another book. In a book that describes just the C++ broker or just the Java broker, each has an introduction that explains that there are two implementations of the broker, and this particular book describes one of them. In the long run, the best solution would be to have the two brokers interop to the point that there are few differences, and one book could easily describe both of them, with a few sections that apply to just one or the other. It might make sense to reflect the docbook levels book, part, and section in our file names, that would make it easier to get an overview of how the files relate to the docbook structure. We currently have files at the book and section levels, but gloss over the fact that parts exist. Before doing any significant restructuring of the files, I'd like to have a clear direction on the structure we want for the documents per se going forward.
        Hide
        Robbie Gemmell added a comment -

        Updating 'Fix For' to Unknown on issues not targeted for 0.8

        Show
        Robbie Gemmell added a comment - Updating 'Fix For' to Unknown on issues not targeted for 0.8
        Hide
        Robbie Gemmell added a comment -

        The duplication is no longer present, resolving.

        Show
        Robbie Gemmell added a comment - The duplication is no longer present, resolving.

          People

          • Assignee:
            Unassigned
            Reporter:
            Martin Ritchie
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development