On Tue, Mar 16, 2010 at 6:12 PM, Robbie Gemmell <[email protected]> wrote: > There were suggestions some months ago around having the website become a > combination of static main pages and generated user doc pages/pdf coming > from the DocBook source, with the wiki hanging off to the side for > development work. Is that still the end game?
Yes it is. After the prototype I did last time, a lot of folks said they would like "blue" instead of "brown" :) I will try to do it this weekend and post another prototype. Hopefully people will like it ! > I'd like to see us pick something (Rajith's suggestions seem like a decent > starting point) and make the switch quickly to stop the process dragging on. > If all design + development related docs stay based on the wiki then the > remainder seems like it has been fairly stagnant, so we should just decide > to draw a line at some and make the DocBook switch, once we can integrate it > into the site that is. > > Robbie > >> -----Original Message----- >> From: Jonathan Robie [mailto:[email protected]] >> Sent: 16 March 2010 15:37 >> To: [email protected] >> Subject: Re: Qpid docs - file structure and organization >> >> 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] > > > > --------------------------------------------------------------------- > 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]
