qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Ritchie <ritch...@apache.org>
Subject Re: Move documentation to svn / DocBook?
Date Wed, 02 Dec 2009 12:00:27 GMT
2009/12/2 Rajith Attapattu <rajith77@gmail.com>:
> 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

I too am a huge +1 on this as being able to tie docs to releases would
be great. It would also make it much easier for users to contribute
patches to the docs.

What were the thoughts about presenting the docbook on our website? As
Aidan mentioned there is a forrest site in svn which could server as
an example for doing the same on trunk.

More details of forrest are here : http://forrest.apache.org but for
me the main highlight is simple management of multiple release
versions on the website.

Cheers

Martin

> 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
>
>



-- 
Martin Ritchie

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


Mime
View raw message