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 Thu, 12 Feb 2009 15:09:06 GMT
On Thu, Feb 12, 2009 at 8:43 AM, Marnie McCormack <
marnie.mccormack@googlemail.com> wrote:

> Being honest, I like the old page far better - escpecially since I just
> added to it/updated it :-)
>

The problem with the old documentation page is that you cannot find
information easily. They are burried all over the place.
For example if I am interested in the JMS client then there is no clear
path/documentation about the JMS client from the main page.
I think that is not a good thing !!
Ex You need to dig through the docs to find the connection URL and bindign
URL docs.

Also the java documentation does not make a clear distinction between broker
docs and JMS client. We have to expect that people who look at the JMS
client may not necessarily be interested in the Java broker or vice-versa.
If I am interested in the JMS Client it would be nice if all the relavent
informaiton are housed under one location.
Isn't that a plus point?


>
> 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.
>

If you noticed, this is one my goals when I tried to whip up the new
documentation page.
I have added a feature page for each component where we can clearly spell
out what is supported.
Currently we don't have a separate feature set for any of the components.
Atleast the java documentation had the features mentioned under
introduction.
But again I think it's best if we have a separate feature doc for the JMS
client and the broker. It makes things simple and clear.


>
> 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.
>

Maintaining docs by language is not a good choice IMHO.
We can clearly see that our users are trying to mix and match components
written in different languages.
Also the c++ broker is packaged by platform and IMO each package is a
different product with possibly different documentation.
After all we are promoting brokers, clients and management tools. So we need
to talk about "our products" rather than group things under language.
So that is the direction I have taken in the new documentation page.

Regards,

Rajith


> Regards,
> Marnie
>
> On Wed, Feb 11, 2009 at 9:29 PM, Carl Trieloff <cctrieloff@redhat.com
> >wrote:
>
> > Rajith Attapattu wrote:
> >
> >> On Wed, Feb 11, 2009 at 3:49 PM, Carl Trieloff <cctrieloff@redhat.com
> >> >wrote:
> >>
> >>
> >>
> >>> I don't like there is a link for each client, I would prefer it to be
> an
> >>> achor to the info on the same page... not links
> >>> to separate pages.. to much clicking around
> >>>
> >>>
> >>
> >>
> >> It can be done in a Similar way to the FAQ page.
> >>
> >>
> >>
> > I think that would one step better.
> >
>



-- 
Regards,

Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/

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