You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Jonathan Robie <jo...@redhat.com> on 2009/12/01 23:13:23 UTC
Move documentation to svn / DocBook?
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 would like to have documentation that is available in either HTML or PDF.
What would you think of using the Wiki for proposals and initial
information that is later moved into the documentation?
What would you think of using DocBook for the documentation itself? I'm
not suggesting using DocBook for the main structure of the web site,
just for documentation.
I've had several people approach me, suggesting this might be a good
approach. How do people who are actually writing documentation feel
about this?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Jonathan Robie <jo...@redhat.com>.
On 12/01/2009 08:20 PM, Aidan Skinner wrote:
> 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.
>
I think one way to make the transition easier is to work bottom up,
picking a set of documents to work on, and doing that in DocBook. I'd
separate the following:
1. Documents - in Docbook
The documentation page is a good place to start looking for candidate
documents:
http://qpid.apache.org/documentation.html
At first blush, I'd like to see one document for each of the following:
* AMQP Messaging Broker (C++ Implementation)
* AMQP Messaging Broker (Java Implementation)
* AMQP Client Programming Tutorials (one per language, using the new
API, references the API docs)
On the C++ / Python side, the new client API tutorials seem like a
logical candidate for the first documents, and I'm likely to start there.
I think the easiest thing to do here is to use the standard Docbook
stylesheets, create some template example files, showing how to mark up
a chapter, and start writing some documents. I have little experience
with Forrest for this kind of thing, but I have read some reviews that
suggest pure DocBook is much more mature for this kind of documentation,
and there are lots of tools for DocBook.
2. Main page of the site - raw HTML?
The main page generally does not change much, and graphical presentation
is important here. Raw HTML gives us a lot of control. I would be
inclined to simpy write a page in HTML for this.
I think this is orthogonal to the documentation per se, and should be
done as a separate project.
3. Navigation pages - Forrest? raw HTML?
We have a small number of navigational pages that get people to other
content. Again, raw HTML can work well for this.
4. Simple HTML pages not intended for other formats
We have pages, like the "Getting Started" page, which probably will be
presented only in HTML. It's easy enough to write them in DocBook and
transform them to HTML. We probably need to version this content along
with the rest of the site.
Would Forrest be helpful for 3 and 4? What advantages would it bring?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Rajith Attapattu <ra...@gmail.com>.
>
> 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.
Most projects will upload an HTML version of the documentation for the
latest release (and the last 2 or 3 releases) into their website
folder and link it from the main page.
The release artifacts will include docs in HTML or pdf. I assume that
was your expectation ??
Website Option 1
----------------------
As for the website, Forrest seems more than adequate.
More complicated websites/documentation have been handled easily with Forrest.
However it seems a bit difficult to get going and it maybe an overkill
for us? Aidan what do you think?
Website Option 2
----------------------
Another idea is for us to isolate all the frequent changing content
into the docbook format and under the doc folder.
The rest of the pages like the Main page, Mailing Lists, Source
Repository, Getting Involved, People page etc... is fairly static.
So we could have a static set of web pages for the above.
Then we could get some help from a graphics guy to create a nice theme
for us with style sheets.
We could apply that theme to our static web pages and our docbook
generated documentation.
This would give our website a much needed facelift in a fairly easy way.
The static webpages and style sheets should live under svn as well (We
could have a top level folder called website).
qpid.apache.org will be pointed to our main index.html
The confluence wiki will be use for what it's designed for rather than
as a website. Our main page will contain a link to the wiki.
I have seen this approach work well in other open source projects.
Website Option 3
----------------------
Yet another idea is to see how we could apply some style sheets to
confluence to make it look pretty.
I googled this a bit but didn't find much info. Anybody else
researched this area?
My personal preference is Option 2. And my least favourable option is Option 3.
Regards,
Rajith
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Martin Ritchie <ri...@apache.org>.
2009/12/2 Rajith Attapattu <ra...@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 <ai...@gmail.com> wrote:
>> On Tue, Dec 1, 2009 at 11:42 PM, Rafael Schloming <ra...@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
Re: Move documentation to svn / DocBook?
Posted by Rajith Attapattu <ra...@gmail.com>.
On Wed, Dec 2, 2009 at 7:31 AM, Rafael Schloming <ra...@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
Re: Move documentation to svn / DocBook?
Posted by Rajith Attapattu <ra...@gmail.com>.
On Wed, Dec 2, 2009 at 9:13 AM, Alan Conway <ac...@redhat.com> wrote:
> On 12/02/2009 07:35 AM, Robert Godfrey wrote:
>>
>> Just like to add my voice to the chorus of +1s, I've been a big advocate
>> of
>> version controlling the docs, and using docbook, for a long time
>>
>> -- Rob
>>
>> 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
>>>
> Another big +1 from me, I'm delighted to see this happening.
>
> Question: can docbook do man pages? There are some problems with the way we
> currently generate the qpidd man pages, wondering if docbook might help us
> there.
A quick google search seems to point to a few such tools.
Ex http://www.oasis-open.org/docbook/tools/dtm/
So it might be a worthwhile experiment.
>
> ---------------------------------------------------------------------
> 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
Re: Move documentation to svn / DocBook?
Posted by Alan Conway <ac...@redhat.com>.
On 12/02/2009 07:35 AM, Robert Godfrey wrote:
> Just like to add my voice to the chorus of +1s, I've been a big advocate of
> version controlling the docs, and using docbook, for a long time
>
> -- Rob
>
> 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
>>
Another big +1 from me, I'm delighted to see this happening.
Question: can docbook do man pages? There are some problems with the way we
currently generate the qpidd man pages, wondering if docbook might help us there.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Robert Godfrey <ro...@gmail.com>.
Just like to add my voice to the chorus of +1s, I've been a big advocate of
version controlling the docs, and using docbook, for a long time
-- Rob
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
>
>
Re: Move documentation to svn / DocBook?
Posted by Alan Conway <ac...@redhat.com>.
On 12/02/2009 11:30 AM, Jonathan Robie wrote:
> On 12/02/2009 07:31 AM, Rafael Schloming wrote:
>> 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.
>
> A lot of what is on the web site involves design notes or descriptions
> of earlier states - I'd like to focus on things that describe how the
> existing release actually works, and ignore the rest.
>
http://cwiki.apache.org/qpid/persistent-cluster-restart-design-note.html
describes current status.
There are other cluster bits & pieces scattered around, I'll try and dig them
all up. If you can get a shell cluster chapter/document in place I can do some
of the cut & paste so you're not stuck doing it all.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Alan Conway <ac...@redhat.com>.
On 12/02/2009 12:11 PM, Rafael Schloming wrote:
> Jonathan Robie wrote:
>>
>> Re: API docs
>>
>> I think the generated C++ and epydoc documentation should be kept in
>> their current formats. I'd like to check in the generated
>> documentation, and point to that from the web site, so it is always up
>> to date. Any objections to this?
>
> I'm +1 on keeping the current formats for api-docs, however I don't
> think we should check in generated content as it can get out of date.
>
I'd suggest just generating the API docs from trunk sources onto the website
periodically. We can generate docs for specific releases separately and include
them in the distribution bundle and on the website. Agree with Rafi, no need to
check them in, we already check in the code that they are generated from.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Rafael Schloming <ra...@redhat.com>.
Jonathan Robie wrote:
>
> Re: API docs
>
> I think the generated C++ and epydoc documentation should be kept in
> their current formats. I'd like to check in the generated documentation,
> and point to that from the web site, so it is always up to date. Any
> objections to this?
I'm +1 on keeping the current formats for api-docs, however I don't
think we should check in generated content as it can get out of date.
--Rafael
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Jonathan Robie <jo...@redhat.com>.
Re: API docs
I think the generated C++ and epydoc documentation should be kept in
their current formats. I'd like to check in the generated documentation,
and point to that from the web site, so it is always up to date. Any
objections to this?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Rafael Schloming <ra...@redhat.com>.
Jonathan Robie wrote:
> On 12/02/2009 07:31 AM, Rafael Schloming wrote:
>> 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.
>
> A lot of what is on the web site involves design notes or descriptions
> of earlier states - I'd like to focus on things that describe how the
> existing release actually works, and ignore the rest.
>
> Ideally, I'd like to improve the organization when moving to DocBook,
> but in the first take, I think we need to identify the most important
> documents and focus on them. Currently, I don't think we really have a
> set of documentation for each broker, or a tutorial for the client APIs.
> But these seem like the most crucial documentation to start with.
>
> A "first take" on the documentation for each broker might simply contain
> the information pointed to in
> http://qpid.apache.org/amqp-messaging-broker-implemented-in-c.html and
> http://qpid.apache.org/amqp-messaging-broker-implemented-in-java.html.
> But I'd like to see each of these quickly get better organized.
>
> What else would you like to see in svn? A priority list would be good.
I meant the *documentation* on the web site, not the entire web site.
Basically everything currently under here:
http://qpid.apache.org/documentation.html
It's not really a priority for me to mess with any of the non
documentation web site content.
--Rafael
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Jonathan Robie <jo...@redhat.com>.
On 12/02/2009 07:31 AM, Rafael Schloming wrote:
> 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.
A lot of what is on the web site involves design notes or descriptions
of earlier states - I'd like to focus on things that describe how the
existing release actually works, and ignore the rest.
Ideally, I'd like to improve the organization when moving to DocBook,
but in the first take, I think we need to identify the most important
documents and focus on them. Currently, I don't think we really have a
set of documentation for each broker, or a tutorial for the client APIs.
But these seem like the most crucial documentation to start with.
A "first take" on the documentation for each broker might simply contain
the information pointed to in
http://qpid.apache.org/amqp-messaging-broker-implemented-in-c.html and
http://qpid.apache.org/amqp-messaging-broker-implemented-in-java.html.
But I'd like to see each of these quickly get better organized.
What else would you like to see in svn? A priority list would be good.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Rafael Schloming <ra...@redhat.com>.
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
Re: Move documentation to svn / DocBook?
Posted by Rajith Attapattu <ra...@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
On Tue, Dec 1, 2009 at 8:20 PM, Aidan Skinner <ai...@gmail.com> wrote:
> On Tue, Dec 1, 2009 at 11:42 PM, Rafael Schloming <ra...@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
Re: Move documentation to svn / DocBook?
Posted by Aidan Skinner <ai...@gmail.com>.
On Tue, Dec 1, 2009 at 11:42 PM, Rafael Schloming <ra...@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
Re: Move documentation to svn / DocBook?
Posted by Rafael Schloming <ra...@redhat.com>.
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.
> I would like to have documentation that is available in either HTML or PDF.
>
> What would you think of using the Wiki for proposals and initial
> information that is later moved into the documentation?
>
> What would you think of using DocBook for the documentation itself? I'm
> not suggesting using DocBook for the main structure of the web site,
> just for documentation.
>
> I've had several people approach me, suggesting this might be a good
> approach. How do people who are actually writing documentation feel
> about this?
I'm strongly in favor of moving the documentation into SVN, putting it
near the corresponding code, and using a text based format for it. This
is the only way I've seen this sort of thing successfully managed for a
project like ours, and IMHO this is critical to improving the quality of
our docs.
I've used docbook before and I would be happy with that choice of
format. For me the most important thing is to be able to update the docs
and the code at the same time in a single commit. This is probably the
only way you're going to get any useful documentation out of me beyond
basic api-doc. ;)
--Rafael
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Move documentation to svn / DocBook?
Posted by Jonathan Robie <jo...@redhat.com>.
On 12/01/2009 05:18 PM, Steve Huston wrote:
>> I would like to have documentation that is available in
>> either HTML or PDF.
>>
> Or others maybe?
>
Absolutely. Here's a nice long list:
http://wiki.docbook.org/topic/formats
And you can develop stylesheets for formats that are missing.
>> What would you think of using the Wiki for proposals and initial
>> information that is later moved into the documentation?
>>
> JIRA?
>
Yes - a very good way to do this.
> I'm not familiar with DocBook... Can you please explain a bit or point
> to more info?
>
DocBook uses XML for source documentation, and converts it to various
formats using XSLT. An awful lot of technical documentation is done in
DocBook.
Here's a good starting point:
http://wiki.docbook.org/topic/FrontPage
I'd say DocBook is the most widely used XML format for technical writing.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
RE: Move documentation to svn / DocBook?
Posted by Steve Huston <sh...@riverace.com>.
> Hi Jonathan,
>
> > 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 would like to have documentation that is available in
> > either HTML or PDF.
>
> Or others maybe?
>
> > What would you think of using the Wiki for proposals and initial
> > information that is later moved into the documentation?
>
> JIRA?
>
> > What would you think of using DocBook for the documentation
> > itself? I'm
> > not suggesting using DocBook for the main structure of the web
site,
>
> > just for documentation.
>
> Sounds good to use a more appropriate tool for docs.
>
> > I've had several people approach me, suggesting this might be a
good
>
> > approach. How do people who are actually writing documentation
feel
> > about this?
>
> I'm not familiar with DocBook... Can you please explain a bit or
point
> to more info?
Ok... I looked up DocBook. An XML-based markup language. Cool... Can
doxygen generated input that works in this scheme? I faintly recall
looking briefly at this a couple years ago and it couldn't at that
point. Or did you envision leaving the API reference out of this plan?
-Steve
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
RE: Move documentation to svn / DocBook?
Posted by Steve Huston <sh...@riverace.com>.
Hi Jonathan,
> 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 would like to have documentation that is available in
> either HTML or PDF.
Or others maybe?
> What would you think of using the Wiki for proposals and initial
> information that is later moved into the documentation?
JIRA?
> What would you think of using DocBook for the documentation
> itself? I'm
> not suggesting using DocBook for the main structure of the web site,
> just for documentation.
Sounds good to use a more appropriate tool for docs.
> I've had several people approach me, suggesting this might be a good
> approach. How do people who are actually writing documentation feel
> about this?
I'm not familiar with DocBook... Can you please explain a bit or point
to more info?
Thanks,
-Steve
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org