qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Ritchie <ritch...@apache.org>
Subject Re: Qpid docs - file structure and organization
Date Wed, 14 Apr 2010 11:11:41 GMT
On 16 March 2010 23:19, Rajith Attapattu <rajith77@gmail.com> wrote:
> On Tue, Mar 16, 2010 at 6:12 PM, Robbie Gemmell
> <robbie.gemmell@gmail.com> 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 think we are in danger of losing some work here. If we don't make
the change soon then we will have docs in svn that users can't easily
access and docs on the wiki that potentially will get lost when the
migration occurs.

It would be great if we could have a time line for replacing the wiki
page with an exported docbook site.

We can work on tweeking the colours once it is live.

Are we in a place where we can just export and see what it is like?

Cheers

Martin

>> 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:jonathan.robie@redhat.com]
>>> Sent: 16 March 2010 15:37
>>> To: dev@qpid.apache.org
>>> 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:dev-subscribe@qpid.apache.org
>>
>>
>>
>> ---------------------------------------------------------------------
>> Apache Qpid - AMQP Messaging Implementation
>> Project:      http://qpid.apache.org
>> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>>
>>
>
>
>
> --
> Regards,
>
> Rajith Attapattu
> Red Hat
> http://rajith.2rlabs.com/
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project:      http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>



-- 
Martin Ritchie

---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org


Mime
View raw message