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 Tue, 01 Dec 2009 23:42:54 GMT
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


Mime
View raw message