qpid-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rajith Attapattu <rajit...@gmail.com>
Subject Re: Qpid Documentation page
Date Fri, 13 Feb 2009 15:29:47 GMT
On Fri, Feb 13, 2009 at 4:05 AM, Marnie McCormack <
marnie.mccormack@googlemail.com> wrote:

> Well put, and aside from any excitement caused (and driving Rafi to read
> our
> docs :-), apologies for my heated response

Marnie no need to apologize. Debating and raising concerns are good and you
are most welcomed to provide your input.

> ! Having had mainly Java docs for
> quite a while, and laid out in such a way that users I sent to the site
> could follow them I'd admit to finding some of the top level changes quite
> C++ oriented. Thus the fustration.

I too agree that the FAQ is a bit C++ -ish.
So we could leave only general stuff in the top level FAQ  and then push C++
or Java specific info in to FAQs under the broker pages.
I see that the java broker has it's own FAQ already. So we can follow a
similar model for the c++ broker.
I could work with Carl/Jonathan and see how best to get the above done.

> In the interests of good karma, I don't mind if you go ahead with the
> DocumentationB page Rajith.
> A list of useful JMS client docs would be a useful addition if you know
> what
> you'd like to see there too - would be happy to contribute ?

For starters I broke down the existing java documentation into the broker
and client section.
Could you please have a look there and see what can be improved?
For the java client I added some empty pages that I plan to fill in as and
when time permits.

Another reason why I broke down the the brokers, clients and management
tools is for us to focus more on providing good documentation for each area.
I see a lot of users on the lists asking questions about a specific client
and would be great if we can point out to the documentation.
When I did this I noticed how sparse the documentation is for most of the
clients with python and ruby having the least.
In contrast to the clients the brokers had decent documentation.



> Jonathan - would behappy for you to do that reorg-ing.
> Marnie
> On Thu, Feb 12, 2009 at 7:27 PM, Rafael Schloming <rafaels@redhat.com
> >wrote:
> > Marnie McCormack wrote:
> >
> >> Being honest, I like the old page far better - escpecially since I just
> >> added to it/updated it :-)
> >>
> >> From my pov, I think it's quite frustrating that all the
> >> broker/implementation boundaries are becoming blurred in the docs & the
> >> way
> >> we link to them.
> >>
> >> For example, the FAQ is not a Qpid wide FAQ and does not make clear
> which
> >> features are present in which broker (see the
> >> paradigms/features/performance
> >> info). For now, the reality is that the language/implementation does
> >> matter
> >> and we should diverge the docs down those lines rather than try to
> >> maintain
> >> a set of 'this is now' docs.
> >>
> >
> > Believe it or not I've never actually read our documentation, however the
> > controversy here inspired me to take a look, and now I feel the need  to
> > supply the perspective from a fresh set of eyes.
> >
> > Comparing just the two top level pages, I found the DocumentationB page
> to
> > be better organized. I felt like it was obvious how to find the
> > documentation for a given area.
> >
> > That said, when clicking down through the links underneath the general
> > portion, I have to agree that what is presented as the general FAQ is
> really
> > mostly about the C++ broker, and the How To guides seem buried at the end
> of
> > the FAQ page rather than being a top level link underneath the respective
> > brokers.
> >
> > So my 2 cents would be keep the top level organization from
> DocumentationB,
> > but add the How To pages in as links underneath the respective brokers,
> and
> > pull most of the stuff from the "General" FAQ into the C++ specific
> > FAQ/HowTo page linked to from the C++ Broker section.
> >
> > --Rafael
> >
> >
> > ---------------------------------------------------------------------
> > Apache Qpid - AMQP Messaging Implementation
> > Project:      http://qpid.apache.org
> > Use/Interact: mailto:dev-subscribe@qpid.apache.org
> >
> >


Rajith Attapattu
Red Hat

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message