qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rafael Schloming <rafa...@redhat.com>
Subject Re: Move documentation to svn / DocBook?
Date Wed, 02 Dec 2009 12:31:24 GMT
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.

--Rafael


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


Mime
View raw message