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