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 04:49:40 GMT
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.

Rajith

On Tue, Dec 1, 2009 at 8:20 PM, Aidan Skinner <aidan.skinner@gmail.com> wrote:
> On Tue, Dec 1, 2009 at 11:42 PM, Rafael Schloming <rafaels@redhat.com> wrote:
>> Jonathan Robie wrote:
>>>
>>> I would like to have documentation that can be versioned, corresponding to
>>> our releases, so that it's easy to identify the documentation that
>>> corresponds to a given release.
>>
>> I think this is critical. There are many times that I would like to be able
>> to refer people to the qpid web site but I can't because the documentation
>> doesn't match the code that they're working with.
>
> Hugely +1 on this. I've tried unsuccesfully to do this twice over the
> last few years. There are remanents of this in the forrest-site branch
> in SVN.
>
> The only word of advice I'll offer, since it didn't succeed before, is
> that it should be done quickly since it's a moving target. If I had
> the time to try again, I might pick a hard cut off date and Just Do
> It.
>
> - Aidan
> --
> Apache Qpid - AMQP, JMS, other messaging love http://qpid.apache.org
> "A witty saying proves nothing" - Voltaire
>
> ---------------------------------------------------------------------
> 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