qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rajith Attapattu <rajit...@gmail.com>
Subject Re: Move documentation to svn / DocBook?
Date Wed, 02 Dec 2009 14:29:23 GMT
On Wed, Dec 2, 2009 at 7:31 AM, Rafael Schloming <rafaels@redhat.com> 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:dev-subscribe@qpid.apache.org
>
>



-- 
Regards,

Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/

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


Mime
View raw message