On Wed, Dec 2, 2009 at 7:31 AM, Rafael Schloming <[email protected]> wrote: > Rajith Attapattu wrote: >> >> I am very pleased to see the support for this approach. >> As Rafi et al pointed out documentation that lives in svn is probably >> the only practical way of ensuring that our dcos match the code and >> vice versa. >> >> Several Apache projects that I was involved in before used this method >> very successfully. >> Where applicable JIRA's were not allowed to be marked resolved until >> there was a commit relating to the relevant documentation. >> The review for the JIRA involved the documentation portion of it as well. >> Releases were sometimes blocked based on outstanding JIRAs for >> documentation ensuring the released product had the proper >> documentation. >> >> I am hoping to support Jonathan in getting the basic infrastructure set >> up. >> It would be great if folks used the new structure when adding >> documentation in the future. >> I am volunteering to slowly convert the existing Java related >> documentation to the doc book format. >> I would appreciate support for other clients. >> >> As for the structure I would like to propose a similar approach to >> what we have in the main documentation page >> http://qpid.apache.org/documentation.html >> >> In terms of the svn layout I envisioned the following. >> We could have a top level doc directory, which contains the main >> docbook file and the Makefile. >> We could then either create dir structure under the top level doc >> folder that mimics the top level components in the main documentation >> page, or we could have the docs for those top level components live >> inside language specific folders we already have. >> >> My personal preference is the former. (For that matter I believe the >> language specific folders as the top dir is not the best for >> organizing the source either, but that's another discussion all >> together). >> I am also hoping to have a nightly automated build for the doc book >> project to ensure it isn't broken. >> >> Please weigh in with your suggestions or alternative proposals. >> As aidan pointed it out, it's best to get this going sooner than later. > > I'm +1 on a top level doc dir. > > In the spirit of getting this done quickly I think it makes sense to do this > in two steps. First get the current content translated into SVN so that the > output matches what we currently have on the website, and then worry about > refining the organization/structure/source-layout later. I'd hate to see the > former stall on a discussion of the latter.
Yes a sensible approach. Perhaps this exercise it self will help us figure what's the best dir layout. > --Rafael > > > --------------------------------------------------------------------- > Apache Qpid - AMQP Messaging Implementation > Project: http://qpid.apache.org > Use/Interact: mailto:[email protected] > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/ --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:[email protected]
