On Tue, Mar 16, 2010 at 11:37 AM, Jonathan Robie
<[email protected]> wrote:
> On 03/16/2010 11:13 AM, Rajith Attapattu wrote:
>>
>> Here are some general comments.
>> Frankly I am not too happy with the current format.
>>
>
> That's fine - the current format was created in order to use existing Wiki
> pages with as little modification as possible, with enough organization for
> the sake of sanity.
My comments were about the existing format rather than the work you had done.
I think you have done excellent work in getting this off the ground !
I was aware that the first step was to get everything exported and
then take it from there.
I just wanted to make sure I sound my concerns early and decisively
before we move forward.
> I want to know where we are heading, and move in that direction, rather than
> polish what we have before setting goals. The most important thing right now
> is to establish a common direction.
>
>> I'd like to see the following in the docs.
>>
>> 1. The user guide should be tied to a particular version, as we are
>> shipping them for each release.
>>
>
> Absolutely. And I think we need to start by setting a goal here. I propopose
> that we aim to have up-to-date docs for release 7 - I can put the release
> number on the front page.
The 0.7 release is a reasonable goal.
> Currently, we have a hodge-podge of docs corresponding to different
> versions, and for some of this material I simply don't know what versions it
> corresponds to.
>
>> 2. The guide should focus on end users, not developers. So we should
>> get rid of all design docs.
>>
>
>
> Agreed.
>
>
>> 3. Our documentation should reflect the goals, vision and direction of
>> the project.
>>
>> a) Brokers with a common set of features
>> b) Management tools that work with both brokers
>> c) Common Client API's
>> d) Interoperability via examples
>>
>
>
> OK.
>
>> 4. I would like to see the TOC as follows.
>>
>> I. Introduction
>> What you have here is fine, but I am not sure about the getting
>> started and download stuff. I need to think about it a bit more.
>>
>
> OK.
>
> I think the goal of the introduction should be:
>
> 1. To introduce the most important concepts briefly
> 2. To show the user how to get up and running, to the point of being able to
> run an example.
Agreed and a large part of this will depend on the examples as well.
In an earlier email Rafi talked about creating a bundle, which
contains a broker, clients, mgt tools and examples.
If we get there, then the getting started guide should be simple in
that you just need to untar it (or install if using rpms) and then run
the examples using the README.
>
>> II. AMQP Messaging Brokers
>> I think rather than having separate sections for each broker, it's
>> best to describe common functionality first then we can have separate
>> chapters for each broker.
>> Recently Rob Godfrey has done a tremendous amount of work to bring
>> the Java broker inline with the c++ broker in terms of features.
>> Ex. Federation, QMF support, LVQ etc... (in addition common
>> features include ACL, Authentication, SSL ..etc)
>>
>> So perhaps the section can be organized as,
>> Chapter 1. Broker concepts (Federation, Security {ACL,
>> Authentication, SSL}, QMF, LVQ ..etc)
>> Chapter 2. Java Broker
>> Chapter 3. C++ Broker
>> (Chapters 2&3 describes the specifics like how to install, run, and
>> configure)
>>
>
>
> This makes sense - I have not been following the Java Broker, I didn't know
> how much progress had been made. Cool!
>
>
>> II. AMQP Messaging Clients
>> We should again explain the common concepts and vision behind the
>> client API's while stating that JMS and WCF are following idioms/API's
>> that are already defined for those domains.
>> The specific chapters on each client will focus on the languages
>> specific items like (how to open a connection, receive a message, send
>> a message ..etc) and the relevant configuration options.
>>
>> Chapter 1. API and addressing syntax.
>> Chapter 2. Python Client
>> Chapter 3. C++ Client
>> Chapter 4. JMS Client
>> Chapter 5. WCF Client
>> Chapter 6. Ruby Client
>>
>
>
> Good. I assume that we will use the high level APIs in all this.
Yes for sure.
I believe the Ruby client will eventually get there as well.
WCF and JMS already has it's own standards based API for the respective domains.
>
>> III. AMQP Messaging Broker Management.
>> This should be a top level section on it's own rather than
>> anything that C++/Java broker specific. A majority of these tools can
>> be used against both.
>> We should state that our brokers can be managed using QMF (and JMX
>> - the Java broker directly and the C++ broker via QMan).
>>
>> Chapter 1. Python management tools - (qpid-config,......)
>> Chapter 2. QMan.
>> QMF-to-JMX bridge
>> QMF-to-WSDM bridge
>> Chapter 3. Eclipse pluggins
>>
>
>
> OK. Any volunteers for the Qman and Eclipse sections?
Hopefully I can get the QMan code working again and perhaps contribute
to the docs.
>
>> IV. QMF
>> This is actually a sub project of Qpid that can be used to manage
>> anything. So IMO it deserves it's own section.
>>
>> Chapter 1. QMF Concepts
>> Chapter 2. QMF C++ API
>> Chapter 2. QMF Python API
>> Chapter 4. QMF Java API
>>
>
> OK
Is this agreeable to you? Lets also see what other folks think
>> V. Testing Frameworks and Tools
>> Here we can talk about our testing frameworks and perf tools
>>
>
> Makes sense.
>
>> VI. Examples/Tutorial
>> I am not still sure about how this section should look like,
>> other than we need one :).
>>
>
> Is this a client API tutorial, an administrator's tutorial, or what? Or do
> we need one of each?
I know I put it down as a section, but I don't know if really need one.
If the client API sections show how to create a connection/session,
send and receive messages, how to configure failover etc.. then I
don't know if we really need a separate examples/tutorials sections.
I believe we can cover enough ground between the getting started and
the Client API's.
But I'd wait till everybody has a chance to chime in.
>> VII. Appendix
>>
>
> OK.
>
> I like this in general.
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:[email protected]
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
