Project Documentation

[Rob Godfrey]

All,

I think we'd all agree our project documentation is not all it could
be.  I've started taking a look at at least making a start on tidying
up some of the docs so that they a) present better and b) are easier
for us to maintain.  I'm looking at the DocBook content at the moment
and I'm trying to get a handle on our current documentation set.

As far as I can tell, we currently publish the following three "books"
from the DocBook sources

* AMQP Messaging Broker (Implemented in C++)
* AMQP Messaging Broker (Implemented in Java)
* Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
JMS, .NET, C++, and Python

The DocBook files we have also contain information for building a
monolithic single book which aggregates all these documents, as well
as including some other files which are not included in the above.
However, as far as I can tell, we are not publishing this.

All the content files, used and unused, are housed in a single
directory with no structure.

What I would like to do immediately is the following:

1) Create a directory structure which reflects the actual organisation
of the documentation, something like

   cpp-broker
   java-broker
   client-programming
   common

and move existing files into the appropriate sub-directory.

2) Remove the (seemingly unused) ability to create a monolithic book

3) Remove all content which is not referenced within the published books.

4) Write a proper makefile which actually works :-)

Once this has been completed, the remaining content will obviously
need to be reviewed... and in the medium term I am hoping that we can
move more and more documentation to be "common" between the brokers.
However, I think the above is probably a necessary prerequisite.

Are people happy with this approach? Is there anything in the
"unpublished" documentation that should be saved?

-- Rob

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Robbie Gemmell]

On 26 April 2012 13:12, Rob Godfrey <[hidden email]> wrote:

> All,
>
> I think we'd all agree our project documentation is not all it could
> be.  I've started taking a look at at least making a start on tidying
> up some of the docs so that they a) present better and b) are easier
> for us to maintain.  I'm looking at the DocBook content at the moment
> and I'm trying to get a handle on our current documentation set.
>
> As far as I can tell, we currently publish the following three "books"
> from the DocBook sources
>
> * AMQP Messaging Broker (Implemented in C++)
> * AMQP Messaging Broker (Implemented in Java)
> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
> JMS, .NET, C++, and Python
>
> The DocBook files we have also contain information for building a
> monolithic single book which aggregates all these documents, as well
> as including some other files which are not included in the above.
> However, as far as I can tell, we are not publishing this.
>
> All the content files, used and unused, are housed in a single
> directory with no structure.
>
> What I would like to do immediately is the following:
>
> 1) Create a directory structure which reflects the actual organisation
> of the documentation, something like
>
>   cpp-broker
>   java-broker
>   client-programming
>   common
>
> and move existing files into the appropriate sub-directory.
>
> 2) Remove the (seemingly unused) ability to create a monolithic book
>
> 3) Remove all content which is not referenced within the published books.
>
> 4) Write a proper makefile which actually works :-)
>
> Once this has been completed, the remaining content will obviously
> need to be reviewed... and in the medium term I am hoping that we can
> move more and more documentation to be "common" between the brokers.
> However, I think the above is probably a necessary prerequisite.
>
> Are people happy with this approach? Is there anything in the
> "unpublished" documentation that should be saved?
>
> -- Rob
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

Sounds like a good approach to me. If there is any of the
'unpublished' content that needs saving, deleting it sounds like a
sure way to draw out anyone actually using it and help us all get onto
a more structured path of storing things.

Robbie

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Gordon Sim]

On 04/26/2012 01:12 PM, Rob Godfrey wrote:
> Are people happy with this approach?

Yes

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Weston M. Price]

I think JCA probably warrants it's own book since there are significant differences from just 'general' client programming.

Regards,

Weston
On Apr 26, 2012, at 8:12 AM, Rob Godfrey wrote:

> All,
>
> I think we'd all agree our project documentation is not all it could
> be.  I've started taking a look at at least making a start on tidying
> up some of the docs so that they a) present better and b) are easier
> for us to maintain.  I'm looking at the DocBook content at the moment
> and I'm trying to get a handle on our current documentation set.
>
> As far as I can tell, we currently publish the following three "books"
> from the DocBook sources
>
> * AMQP Messaging Broker (Implemented in C++)
> * AMQP Messaging Broker (Implemented in Java)
> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
> JMS, .NET, C++, and Python
>
> The DocBook files we have also contain information for building a
> monolithic single book which aggregates all these documents, as well
> as including some other files which are not included in the above.
> However, as far as I can tell, we are not publishing this.
>
> All the content files, used and unused, are housed in a single
> directory with no structure.
>
> What I would like to do immediately is the following:
>
> 1) Create a directory structure which reflects the actual organisation
> of the documentation, something like
>
>   cpp-broker
>   java-broker
>   client-programming
>   common
>
> and move existing files into the appropriate sub-directory.
>
> 2) Remove the (seemingly unused) ability to create a monolithic book
>
> 3) Remove all content which is not referenced within the published books.
>
> 4) Write a proper makefile which actually works :-)
>
> Once this has been completed, the remaining content will obviously
> need to be reviewed... and in the medium term I am hoping that we can
> move more and more documentation to be "common" between the brokers.
> However, I think the above is probably a necessary prerequisite.
>
> Are people happy with this approach? Is there anything in the
> "unpublished" documentation that should be saved?
>
> -- Rob
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Rob Godfrey]

Hi Weston,

does the book exist currently?

All I'm talking about right now is re-organising the current
documentation and removing unused stuff.  I don't see a current JCA
book being published.

-- Rob

On 26 April 2012 15:32, Weston M. Price <[hidden email]> wrote:

> I think JCA probably warrants it's own book since there are significant differences from just 'general' client programming.
>
> Regards,
>
> Weston
> On Apr 26, 2012, at 8:12 AM, Rob Godfrey wrote:
>
>> All,
>>
>> I think we'd all agree our project documentation is not all it could
>> be.  I've started taking a look at at least making a start on tidying
>> up some of the docs so that they a) present better and b) are easier
>> for us to maintain.  I'm looking at the DocBook content at the moment
>> and I'm trying to get a handle on our current documentation set.
>>
>> As far as I can tell, we currently publish the following three "books"
>> from the DocBook sources
>>
>> * AMQP Messaging Broker (Implemented in C++)
>> * AMQP Messaging Broker (Implemented in Java)
>> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
>> JMS, .NET, C++, and Python
>>
>> The DocBook files we have also contain information for building a
>> monolithic single book which aggregates all these documents, as well
>> as including some other files which are not included in the above.
>> However, as far as I can tell, we are not publishing this.
>>
>> All the content files, used and unused, are housed in a single
>> directory with no structure.
>>
>> What I would like to do immediately is the following:
>>
>> 1) Create a directory structure which reflects the actual organisation
>> of the documentation, something like
>>
>>   cpp-broker
>>   java-broker
>>   client-programming
>>   common
>>
>> and move existing files into the appropriate sub-directory.
>>
>> 2) Remove the (seemingly unused) ability to create a monolithic book
>>
>> 3) Remove all content which is not referenced within the published books.
>>
>> 4) Write a proper makefile which actually works :-)
>>
>> Once this has been completed, the remaining content will obviously
>> need to be reviewed... and in the medium term I am hoping that we can
>> move more and more documentation to be "common" between the brokers.
>> However, I think the above is probably a necessary prerequisite.
>>
>> Are people happy with this approach? Is there anything in the
>> "unpublished" documentation that should be saved?
>>
>> -- Rob
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Weston M. Price]

Hey Rob,
        No, we currently don't have one. I thought with re-organizing things it might be a good time to do it.

Regards,

Weston

On Apr 26, 2012, at 9:55 AM, Rob Godfrey wrote:

> Hi Weston,
>
> does the book exist currently?
>
> All I'm talking about right now is re-organising the current
> documentation and removing unused stuff.  I don't see a current JCA
> book being published.
>
> -- Rob
>
> On 26 April 2012 15:32, Weston M. Price <[hidden email]> wrote:
>> I think JCA probably warrants it's own book since there are significant differences from just 'general' client programming.
>>
>> Regards,
>>
>> Weston
>> On Apr 26, 2012, at 8:12 AM, Rob Godfrey wrote:
>>
>>> All,
>>>
>>> I think we'd all agree our project documentation is not all it could
>>> be.  I've started taking a look at at least making a start on tidying
>>> up some of the docs so that they a) present better and b) are easier
>>> for us to maintain.  I'm looking at the DocBook content at the moment
>>> and I'm trying to get a handle on our current documentation set.
>>>
>>> As far as I can tell, we currently publish the following three "books"
>>> from the DocBook sources
>>>
>>> * AMQP Messaging Broker (Implemented in C++)
>>> * AMQP Messaging Broker (Implemented in Java)
>>> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
>>> JMS, .NET, C++, and Python
>>>
>>> The DocBook files we have also contain information for building a
>>> monolithic single book which aggregates all these documents, as well
>>> as including some other files which are not included in the above.
>>> However, as far as I can tell, we are not publishing this.
>>>
>>> All the content files, used and unused, are housed in a single
>>> directory with no structure.
>>>
>>> What I would like to do immediately is the following:
>>>
>>> 1) Create a directory structure which reflects the actual organisation
>>> of the documentation, something like
>>>
>>>   cpp-broker
>>>   java-broker
>>>   client-programming
>>>   common
>>>
>>> and move existing files into the appropriate sub-directory.
>>>
>>> 2) Remove the (seemingly unused) ability to create a monolithic book
>>>
>>> 3) Remove all content which is not referenced within the published books.
>>>
>>> 4) Write a proper makefile which actually works :-)
>>>
>>> Once this has been completed, the remaining content will obviously
>>> need to be reviewed... and in the medium term I am hoping that we can
>>> move more and more documentation to be "common" between the brokers.
>>> However, I think the above is probably a necessary prerequisite.
>>>
>>> Are people happy with this approach? Is there anything in the
>>> "unpublished" documentation that should be saved?
>>>
>>> -- Rob
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: [hidden email]
>>> For additional commands, e-mail: [hidden email]
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Rob Godfrey]

OK, just checking...

Unless anyone objects I'd like to do the reorganization ASAP so we can
then start adding useful docs.

The other question I forgot to ask is...

Do we need to keep on generating the "single large page" HTML version
in addition to the PDF and chunked HTML.  I can't really see any
advantage to it - so anyone object to me killing its production?

-- Rob

On 26 April 2012 16:04, Weston M. Price <[hidden email]> wrote:

> Hey Rob,
>        No, we currently don't have one. I thought with re-organizing things it might be a good time to do it.
>
> Regards,
>
> Weston
>
> On Apr 26, 2012, at 9:55 AM, Rob Godfrey wrote:
>
>> Hi Weston,
>>
>> does the book exist currently?
>>
>> All I'm talking about right now is re-organising the current
>> documentation and removing unused stuff.  I don't see a current JCA
>> book being published.
>>
>> -- Rob
>>
>> On 26 April 2012 15:32, Weston M. Price <[hidden email]> wrote:
>>> I think JCA probably warrants it's own book since there are significant differences from just 'general' client programming.
>>>
>>> Regards,
>>>
>>> Weston
>>> On Apr 26, 2012, at 8:12 AM, Rob Godfrey wrote:
>>>
>>>> All,
>>>>
>>>> I think we'd all agree our project documentation is not all it could
>>>> be.  I've started taking a look at at least making a start on tidying
>>>> up some of the docs so that they a) present better and b) are easier
>>>> for us to maintain.  I'm looking at the DocBook content at the moment
>>>> and I'm trying to get a handle on our current documentation set.
>>>>
>>>> As far as I can tell, we currently publish the following three "books"
>>>> from the DocBook sources
>>>>
>>>> * AMQP Messaging Broker (Implemented in C++)
>>>> * AMQP Messaging Broker (Implemented in Java)
>>>> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
>>>> JMS, .NET, C++, and Python
>>>>
>>>> The DocBook files we have also contain information for building a
>>>> monolithic single book which aggregates all these documents, as well
>>>> as including some other files which are not included in the above.
>>>> However, as far as I can tell, we are not publishing this.
>>>>
>>>> All the content files, used and unused, are housed in a single
>>>> directory with no structure.
>>>>
>>>> What I would like to do immediately is the following:
>>>>
>>>> 1) Create a directory structure which reflects the actual organisation
>>>> of the documentation, something like
>>>>
>>>>   cpp-broker
>>>>   java-broker
>>>>   client-programming
>>>>   common
>>>>
>>>> and move existing files into the appropriate sub-directory.
>>>>
>>>> 2) Remove the (seemingly unused) ability to create a monolithic book
>>>>
>>>> 3) Remove all content which is not referenced within the published books.
>>>>
>>>> 4) Write a proper makefile which actually works :-)
>>>>
>>>> Once this has been completed, the remaining content will obviously
>>>> need to be reviewed... and in the medium term I am hoping that we can
>>>> move more and more documentation to be "common" between the brokers.
>>>> However, I think the above is probably a necessary prerequisite.
>>>>
>>>> Are people happy with this approach? Is there anything in the
>>>> "unpublished" documentation that should be saved?
>>>>
>>>> -- Rob
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: [hidden email]
>>>> For additional commands, e-mail: [hidden email]
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: [hidden email]
>>> For additional commands, e-mail: [hidden email]
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Weston M. Price]

On Apr 26, 2012, at 10:07 AM, Rob Godfrey wrote:

> OK, just checking...
>
> Unless anyone objects I'd like to do the reorganization ASAP so we can
> then start adding useful docs.

Agreed.
>
> The other question I forgot to ask is...
>
> Do we need to keep on generating the "single large page" HTML version
> in addition to the PDF and chunked HTML.  I can't really see any
> advantage to it - so anyone object to me killing its production?
>

Not at all.

> -- Rob
>
> On 26 April 2012 16:04, Weston M. Price <[hidden email]> wrote:
>> Hey Rob,
>>        No, we currently don't have one. I thought with re-organizing things it might be a good time to do it.
>>
>> Regards,
>>
>> Weston
>>
>> On Apr 26, 2012, at 9:55 AM, Rob Godfrey wrote:
>>
>>> Hi Weston,
>>>
>>> does the book exist currently?
>>>
>>> All I'm talking about right now is re-organising the current
>>> documentation and removing unused stuff.  I don't see a current JCA
>>> book being published.
>>>
>>> -- Rob
>>>
>>> On 26 April 2012 15:32, Weston M. Price <[hidden email]> wrote:
>>>> I think JCA probably warrants it's own book since there are significant differences from just 'general' client programming.
>>>>
>>>> Regards,
>>>>
>>>> Weston
>>>> On Apr 26, 2012, at 8:12 AM, Rob Godfrey wrote:
>>>>
>>>>> All,
>>>>>
>>>>> I think we'd all agree our project documentation is not all it could
>>>>> be.  I've started taking a look at at least making a start on tidying
>>>>> up some of the docs so that they a) present better and b) are easier
>>>>> for us to maintain.  I'm looking at the DocBook content at the moment
>>>>> and I'm trying to get a handle on our current documentation set.
>>>>>
>>>>> As far as I can tell, we currently publish the following three "books"
>>>>> from the DocBook sources
>>>>>
>>>>> * AMQP Messaging Broker (Implemented in C++)
>>>>> * AMQP Messaging Broker (Implemented in Java)
>>>>> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
>>>>> JMS, .NET, C++, and Python
>>>>>
>>>>> The DocBook files we have also contain information for building a
>>>>> monolithic single book which aggregates all these documents, as well
>>>>> as including some other files which are not included in the above.
>>>>> However, as far as I can tell, we are not publishing this.
>>>>>
>>>>> All the content files, used and unused, are housed in a single
>>>>> directory with no structure.
>>>>>
>>>>> What I would like to do immediately is the following:
>>>>>
>>>>> 1) Create a directory structure which reflects the actual organisation
>>>>> of the documentation, something like
>>>>>
>>>>>   cpp-broker
>>>>>   java-broker
>>>>>   client-programming
>>>>>   common
>>>>>
>>>>> and move existing files into the appropriate sub-directory.
>>>>>
>>>>> 2) Remove the (seemingly unused) ability to create a monolithic book
>>>>>
>>>>> 3) Remove all content which is not referenced within the published books.
>>>>>
>>>>> 4) Write a proper makefile which actually works :-)
>>>>>
>>>>> Once this has been completed, the remaining content will obviously
>>>>> need to be reviewed... and in the medium term I am hoping that we can
>>>>> move more and more documentation to be "common" between the brokers.
>>>>> However, I think the above is probably a necessary prerequisite.
>>>>>
>>>>> Are people happy with this approach? Is there anything in the
>>>>> "unpublished" documentation that should be saved?
>>>>>
>>>>> -- Rob
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: [hidden email]
>>>>> For additional commands, e-mail: [hidden email]
>>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: [hidden email]
>>>> For additional commands, e-mail: [hidden email]
>>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: [hidden email]
>>> For additional commands, e-mail: [hidden email]
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Robbie Gemmell]

On 26 April 2012 15:07, Rob Godfrey <[hidden email]> wrote:

> OK, just checking...
>
> Unless anyone objects I'd like to do the reorganization ASAP so we can
> then start adding useful docs.
>
> The other question I forgot to ask is...
>
> Do we need to keep on generating the "single large page" HTML version
> in addition to the PDF and chunked HTML.  I can't really see any
> advantage to it - so anyone object to me killing its production?
>
> -- Rob

We didnt link it from the site for quite some time even though it was
being built so I raised the topic of deleting it as a result. It
eventually got linked to instead, but I still dont think its that
useful and remain +1 for deleting it.

Robbie

>
> On 26 April 2012 16:04, Weston M. Price <[hidden email]> wrote:
>> Hey Rob,
>>        No, we currently don't have one. I thought with re-organizing things it might be a good time to do it.
>>
>> Regards,
>>
>> Weston
>>
>> On Apr 26, 2012, at 9:55 AM, Rob Godfrey wrote:
>>
>>> Hi Weston,
>>>
>>> does the book exist currently?
>>>
>>> All I'm talking about right now is re-organising the current
>>> documentation and removing unused stuff.  I don't see a current JCA
>>> book being published.
>>>
>>> -- Rob
>>>
>>> On 26 April 2012 15:32, Weston M. Price <[hidden email]> wrote:
>>>> I think JCA probably warrants it's own book since there are significant differences from just 'general' client programming.
>>>>
>>>> Regards,
>>>>
>>>> Weston
>>>> On Apr 26, 2012, at 8:12 AM, Rob Godfrey wrote:
>>>>
>>>>> All,
>>>>>
>>>>> I think we'd all agree our project documentation is not all it could
>>>>> be.  I've started taking a look at at least making a start on tidying
>>>>> up some of the docs so that they a) present better and b) are easier
>>>>> for us to maintain.  I'm looking at the DocBook content at the moment
>>>>> and I'm trying to get a handle on our current documentation set.
>>>>>
>>>>> As far as I can tell, we currently publish the following three "books"
>>>>> from the DocBook sources
>>>>>
>>>>> * AMQP Messaging Broker (Implemented in C++)
>>>>> * AMQP Messaging Broker (Implemented in Java)
>>>>> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
>>>>> JMS, .NET, C++, and Python
>>>>>
>>>>> The DocBook files we have also contain information for building a
>>>>> monolithic single book which aggregates all these documents, as well
>>>>> as including some other files which are not included in the above.
>>>>> However, as far as I can tell, we are not publishing this.
>>>>>
>>>>> All the content files, used and unused, are housed in a single
>>>>> directory with no structure.
>>>>>
>>>>> What I would like to do immediately is the following:
>>>>>
>>>>> 1) Create a directory structure which reflects the actual organisation
>>>>> of the documentation, something like
>>>>>
>>>>>   cpp-broker
>>>>>   java-broker
>>>>>   client-programming
>>>>>   common
>>>>>
>>>>> and move existing files into the appropriate sub-directory.
>>>>>
>>>>> 2) Remove the (seemingly unused) ability to create a monolithic book
>>>>>
>>>>> 3) Remove all content which is not referenced within the published books.
>>>>>
>>>>> 4) Write a proper makefile which actually works :-)
>>>>>
>>>>> Once this has been completed, the remaining content will obviously
>>>>> need to be reviewed... and in the medium term I am hoping that we can
>>>>> move more and more documentation to be "common" between the brokers.
>>>>> However, I think the above is probably a necessary prerequisite.
>>>>>
>>>>> Are people happy with this approach? Is there anything in the
>>>>> "unpublished" documentation that should be saved?
>>>>>
>>>>> -- Rob
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: [hidden email]
>>>>> For additional commands, e-mail: [hidden email]
>>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: [hidden email]
>>>> For additional commands, e-mail: [hidden email]
>>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: [hidden email]
>>> For additional commands, e-mail: [hidden email]
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

[Rob Godfrey]

OK - I've checked in my first pass at these changes... for the moment
I've just moved the content that was not being referenced into an
"old" directory to give people a chance to review and resurrect it if
it is still useful.

The generation of the single html file no longer takes place.

-- Rob

On 26 April 2012 17:40, Robbie Gemmell <[hidden email]> wrote:

> On 26 April 2012 15:07, Rob Godfrey <[hidden email]> wrote:
>> OK, just checking...
>>
>> Unless anyone objects I'd like to do the reorganization ASAP so we can
>> then start adding useful docs.
>>
>> The other question I forgot to ask is...
>>
>> Do we need to keep on generating the "single large page" HTML version
>> in addition to the PDF and chunked HTML.  I can't really see any
>> advantage to it - so anyone object to me killing its production?
>>
>> -- Rob
>
> We didnt link it from the site for quite some time even though it was
> being built so I raised the topic of deleting it as a result. It
> eventually got linked to instead, but I still dont think its that
> useful and remain +1 for deleting it.
>
> Robbie
>
>>
>> On 26 April 2012 16:04, Weston M. Price <[hidden email]> wrote:
>>> Hey Rob,
>>>        No, we currently don't have one. I thought with re-organizing things it might be a good time to do it.
>>>
>>> Regards,
>>>
>>> Weston
>>>
>>> On Apr 26, 2012, at 9:55 AM, Rob Godfrey wrote:
>>>
>>>> Hi Weston,
>>>>
>>>> does the book exist currently?
>>>>
>>>> All I'm talking about right now is re-organising the current
>>>> documentation and removing unused stuff.  I don't see a current JCA
>>>> book being published.
>>>>
>>>> -- Rob
>>>>
>>>> On 26 April 2012 15:32, Weston M. Price <[hidden email]> wrote:
>>>>> I think JCA probably warrants it's own book since there are significant differences from just 'general' client programming.
>>>>>
>>>>> Regards,
>>>>>
>>>>> Weston
>>>>> On Apr 26, 2012, at 8:12 AM, Rob Godfrey wrote:
>>>>>
>>>>>> All,
>>>>>>
>>>>>> I think we'd all agree our project documentation is not all it could
>>>>>> be.  I've started taking a look at at least making a start on tidying
>>>>>> up some of the docs so that they a) present better and b) are easier
>>>>>> for us to maintain.  I'm looking at the DocBook content at the moment
>>>>>> and I'm trying to get a handle on our current documentation set.
>>>>>>
>>>>>> As far as I can tell, we currently publish the following three "books"
>>>>>> from the DocBook sources
>>>>>>
>>>>>> * AMQP Messaging Broker (Implemented in C++)
>>>>>> * AMQP Messaging Broker (Implemented in Java)
>>>>>> * Programming in Apache Qpid: Cross-Platform AMQP Messaging in Java
>>>>>> JMS, .NET, C++, and Python
>>>>>>
>>>>>> The DocBook files we have also contain information for building a
>>>>>> monolithic single book which aggregates all these documents, as well
>>>>>> as including some other files which are not included in the above.
>>>>>> However, as far as I can tell, we are not publishing this.
>>>>>>
>>>>>> All the content files, used and unused, are housed in a single
>>>>>> directory with no structure.
>>>>>>
>>>>>> What I would like to do immediately is the following:
>>>>>>
>>>>>> 1) Create a directory structure which reflects the actual organisation
>>>>>> of the documentation, something like
>>>>>>
>>>>>>   cpp-broker
>>>>>>   java-broker
>>>>>>   client-programming
>>>>>>   common
>>>>>>
>>>>>> and move existing files into the appropriate sub-directory.
>>>>>>
>>>>>> 2) Remove the (seemingly unused) ability to create a monolithic book
>>>>>>
>>>>>> 3) Remove all content which is not referenced within the published books.
>>>>>>
>>>>>> 4) Write a proper makefile which actually works :-)
>>>>>>
>>>>>> Once this has been completed, the remaining content will obviously
>>>>>> need to be reviewed... and in the medium term I am hoping that we can
>>>>>> move more and more documentation to be "common" between the brokers.
>>>>>> However, I think the above is probably a necessary prerequisite.
>>>>>>
>>>>>> Are people happy with this approach? Is there anything in the
>>>>>> "unpublished" documentation that should be saved?
>>>>>>
>>>>>> -- Rob
>>>>>>
>>>>>> ---------------------------------------------------------------------
>>>>>> To unsubscribe, e-mail: [hidden email]
>>>>>> For additional commands, e-mail: [hidden email]
>>>>>>
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: [hidden email]
>>>>> For additional commands, e-mail: [hidden email]
>>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: [hidden email]
>>>> For additional commands, e-mail: [hidden email]
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: [hidden email]
>>> For additional commands, e-mail: [hidden email]
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]