+1, I suggested to Senaka that we start with adding a README for each example. Users are most likely to read them and would resort to readign tutorial if they get stuck.
However we also a need the more comphrehensive documentation. And as Alan said it is nice if we have them under svn and use a site generation tool to get the PDF/HTML ..etc. Having it in svn will allow us to easily to version specific documentaiton as well. We can start this by having a tutorial for the mult languages examples. Senaka and I are planning to do this with Jonathans help. Configuration guides for the brokers will be tackled next unless we have more volunteers. Regards, Rajith On Fri, Apr 25, 2008 at 4:30 PM, Alan Conway <[EMAIL PROTECTED]> wrote: > 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. > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/
