[jira] Commented: (QPID-2725) Large quantities of documentation are duplicated

["Jonathan Robie (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/QPID-2725?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12923873#action_12923873 ] 

Jonathan Robie commented on QPID-2725:
--------------------------------------

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.

> Large quantities of documentation are duplicated 
> -------------------------------------------------
>
>                 Key: QPID-2725
>                 URL: https://issues.apache.org/jira/browse/QPID-2725
>             Project: Qpid
>          Issue Type: Bug
>            Reporter: Martin Ritchie
>            Priority: Critical
>             Fix For: 0.7
>
>
> 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.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org