Senaka Fernando wrote:
Hi all,
According to the present discussion, I think it would be best to wait a bit
until Jonathan can come to an agreement about how the example documentation
could be made use in Qpid. However, there are certain other areas in which I
can start work on, some that Jonathan's docs don't focus.
1. How to run the examples. I mean the order.
It is important that we describe the order in which the constitutes of
each example must be run, and the reason behind it. It should also detail
the results seen on the broker side (explanation on the trace logs), and
also something similar on the client side. This raises a new question. How I
can I enable trace logs on the client side?
2. Some docs on the RedHat site are not quite right, and not quite complete.
I'm not attempting to point them on this list, as I don't know the legality
of such a statement. Thus, I would like to talk in person to anyone
responsible on those documentation, on behalf of Qpid, should there be any
need.
3. We need to create a README per example, at least a tiny one. People
wouldn't otherwise have a clue when the try it for the first time. I can get
going on this now.
4. And, as Danushka stated, +1 for including these to the docs. I mean the
docs found inside the docs folder.
5. Also, I need to know where on the wiki I should start writing
documentation on examples. I didn't get an answer to that as yet.
I like to see as much documentation as possible living with or in the code, as
that makes it more likely to be kept up to date. We use doxygen for API
documentation, it's quite flexible and perhaps can be used creatively to embed
documentation in the example source such that it is also possible to generate a
nicely formatted PDF or HTML document.
If we do use separate doc format like docbook (and I can see reasons for that
too) then we could generate HTML or text READMEs into the example directories.
I'm not keen on putting documentation on the wiki because it is almost
impossible to synchronize docs on the wiki with changing versions of the code. I
think whatever format it takes, documentation sources should live in SVN with
the code. We can of course generate HTML/PDF to be published on the apache site
for released versions etc.
Cheers,
Alan.
