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-subscr...@qpid.apache.org
