On 26 April 2012 13:12, Rob Godfrey <[email protected]> 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: [email protected] > For additional commands, e-mail: [email protected] >
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: [email protected] For additional commands, e-mail: [email protected]
