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.
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.
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.
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.
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?
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
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?
VII. Appendix
OK.
I like this in general.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
