qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alan Conway <acon...@redhat.com>
Subject Re: Improving docs on C++ examples
Date Fri, 25 Apr 2008 20:30:06 GMT
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.

Mime
View raw message