You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Rajith Attapattu <ra...@gmail.com> on 2009/02/11 19:05:48 UTC
Qpid Documentation page
Hi All,
I had a stab at re organizing the Qpid documentation page.
Looking at dev/user list I found that several users had a bit of trouble
finding out the info they are looking for.
The goals for the re-org are,
1. Provide a top level index of documentation broken down by functional
area.
2. Organize all relavent information in one location (Ex all user guides/How
To's for JMS client under one location and not mix it up with broker docs)
3. Try to make a clear separation between user guides vs developer
information.
4. Build up a list of links/content that we need to maintain every release
..etc
http://cwiki.apache.org/confluence/display/qpid/DocumentationB
The above link is work in progress and comments/suggestions are most
welcomed.
Once everybody is happy about the direction/content I would like to replace
the current documentation page with the contents in the above link.
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
Re: Qpid Documentation page
Posted by Jonathan Robie <jo...@redhat.com>.
Marnie McCormack wrote:
> I'm not sure what the answer here is, as you're right about the multiple
> differing views issue.
>
> My take on it (and it is a little one sided) is to approach the pages as a
> User tries to find something out, usually (inevitably) as a Java dev.
>
> Not sure about a better way fwd tho ... will ponder.
>
We could look at this from a workflow perspective - ideally, the top
level pages should not have to change significantly when new
documentation is added for a given broker or client API or tool, so the
people who create each of these bits of software can work relatively
independently.
If we take that approach, then the top level pages should point to
documentation for a given component, but not try to present a global FAQ
that pertains to all components.
If this sounds promising, I can work up a proposed organization along
these lines early next week (the rest of this week is pretty much booked
for me). If this does not sound promising, I'll avoid the extra work ;->
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Documentation page
Posted by Marnie McCormack <ma...@googlemail.com>.
I'm not sure what the answer here is, as you're right about the multiple
differing views issue.
My take on it (and it is a little one sided) is to approach the pages as a
User tries to find something out, usually (inevitably) as a Java dev.
Not sure about a better way fwd tho ... will ponder.
Marnie
On Thu, Feb 12, 2009 at 2:32 PM, Jonathan Robie
<jo...@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.
>>
>>
>
> One problem we're having: there are many ways we could organize this
> information, and when people do individual pages, they each use a given
> organization. Sometimes we see multiple approaches to organization on the
> same page.
>
> Is that inherent to our group editing approach using a Wiki, or is there a
> good way to get a handle on this?
>
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
Re: Qpid Documentation page
Posted by Jonathan Robie <jo...@redhat.com>.
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.
>
One problem we're having: there are many ways we could organize this
information, and when people do individual pages, they each use a given
organization. Sometimes we see multiple approaches to organization on
the same page.
Is that inherent to our group editing approach using a Wiki, or is there
a good way to get a handle on this?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Documentation page
Posted by Rajith Attapattu <ra...@gmail.com>.
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.
Regards,
Rajith
>
>
> 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
> >
> >
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
Re: Qpid Documentation page
Posted by Marnie McCormack <ma...@googlemail.com>.
Well put, and aside from any excitement caused (and driving Rafi to read our
docs :-), apologies for my heated response ! 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.
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 ?
Jonathan - would behappy for you to do that reorg-ing.
Marnie
On Thu, Feb 12, 2009 at 7:27 PM, Rafael Schloming <ra...@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
>
>
Re: Qpid Documentation page
Posted by Jonathan Robie <jo...@redhat.com>.
Rafael Schloming wrote:
> 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.
I agree.
> 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.
If someone doesn't tell me to hold off, I'll be doing some of this kind
of reorganization early next week.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Documentation page
Posted by Rafael Schloming <ra...@redhat.com>.
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
Re: Qpid Documentation page
Posted by Rajith Attapattu <ra...@gmail.com>.
On Thu, Feb 12, 2009 at 10:28 AM, Marnie McCormack <
marnie.mccormack@googlemail.com> wrote:
> >
> > <snip>
> > 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.
> >
> >
>
> Our products cannot currently be discussed as one thing, be it broker or
> client, and we're watering down the value of our docs by trying to make it
> all language independent. The also cannot mix & match easily. This is the
> future (and slightly the past) but now the present.
>
> On the Java side, we can address the things you think aren't great about
> our
> existing docs - but for now the language distinction is the only sensible
> one that I can see.
>
> On the C++, the packaging by platform is a new one on me - i thought we
> distributed one thing for the cpp ? OPther places may host convenience
> builds, but do we have them on Apache ?
>
We (as in Apache) don't offer different builds. We simply release the
source.
But the build instructions and setup may be different for each platform.
Certian features also are by platform. (Ex RDMA)
So you the documentation would need to address these concerns.
>
> I get a little irate when the Java docs get buried under a top level doc
> which isn't specific enough to be useful.
Could you please explain this a bit more? Are you refering to the old
documentation or the new documentation page?
looking at this link http://cwiki.apache.org/qpid/documentation.html - could
you please tell me where I can quickly jump to the JMS client documentation
if I want to know about the connection URL?
To me the old documentation is not useful and looks disorganized. There were
several users who had to ask on the list to find out the information they
need. Thats what prompted me to have a go at the documentation.
If you look at the following link
http://cwiki.apache.org/confluence/display/qpid/DocumentationB
There is a clear logical path a user can follow to get to the information
they are looking for.
Perhaps I didn't fully understand your concern. If so my appologies.
Rajith
> Here endeth my tirade ....
>
>
> Marnie
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
Re: Qpid Documentation page
Posted by Marnie McCormack <ma...@googlemail.com>.
>
> <snip>
> 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.
>
>
Our products cannot currently be discussed as one thing, be it broker or
client, and we're watering down the value of our docs by trying to make it
all language independent. The also cannot mix & match easily. This is the
future (and slightly the past) but now the present.
On the Java side, we can address the things you think aren't great about our
existing docs - but for now the language distinction is the only sensible
one that I can see.
On the C++, the packaging by platform is a new one on me - i thought we
distributed one thing for the cpp ? OPther places may host convenience
builds, but do we have them on Apache ?
I get a little irate when the Java docs get buried under a top level doc
which isn't specific enough to be useful. Here endeth my tirade ....
Marnie
Re: Qpid Documentation page
Posted by Rajith Attapattu <ra...@gmail.com>.
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/
Re: Qpid Documentation page
Posted by Marnie McCormack <ma...@googlemail.com>.
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.
Regards,
Marnie
On Wed, Feb 11, 2009 at 9:29 PM, Carl Trieloff <cc...@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.
>
Re: Qpid Documentation page
Posted by Carl Trieloff <cc...@redhat.com>.
Rajith Attapattu wrote:
> On Wed, Feb 11, 2009 at 3:49 PM, Carl Trieloff <cc...@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.
Re: Qpid Documentation page
Posted by Rajith Attapattu <ra...@gmail.com>.
On Wed, Feb 11, 2009 at 3:49 PM, Carl Trieloff <cc...@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.
Rajtih
>
>
> Carl.
>
>
>
> Rajith Attapattu wrote:
>
>> On Wed, Feb 11, 2009 at 1:25 PM, Jonathan Robie
>> <jo...@redhat.com>wrote:
>>
>>
>>
>>> Rajith Attapattu wrote:
>>>
>>>
>>>
>>>> Jonathan, appologies if I wasn't clear enough.
>>>>
>>>> The goal was to replace the current documentaiton page at
>>>> http://cwiki.apache.org/confluence/display/qpid/Documentation with the
>>>> proposed
>>>> http://cwiki.apache.org/confluence/display/qpid/DocumentationB
>>>>
>>>> The reason why I created a parallel page was for folks to compare the
>>>> two
>>>> and make decesion.
>>>> Since this was a main page I didn't want to arbitarily reorganize it
>>>> without
>>>> getting any approval/feedback from the community.
>>>>
>>>>
>>>>
>>>>
>>> Whew! I apologize for being stupid and alarmist here ;->
>>>
>>> I like your new page better, but I think we need sections by language,
>>> showing the API guides and examples for each language.
>>>
>>>
>>
>>
>> If you click on a particular client, there is a link to the API guides (if
>> available)
>> Examples are listed as a top level link.
>>
>> I am not sure if there is a point in having sections by language, rather
>> it
>> should be by messaging client.
>> After all the API guides that we have currenty are for the messaging
>> clients.
>>
>> Now there will be API guides for QMF as well. Ex the python and c++ based
>> API's.
>> We need to make sure we distinguish properly between these API's and the
>> messaging client API's
>>
>> Regards,
>>
>> Rajith
>>
>>
>>
>>
>>> Jonathan
>>>
>>>
>>> ---------------------------------------------------------------------
>>> 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/
Re: Qpid Documentation page
Posted by Carl Trieloff <cc...@redhat.com>.
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
Carl.
Rajith Attapattu wrote:
> On Wed, Feb 11, 2009 at 1:25 PM, Jonathan Robie
> <jo...@redhat.com>wrote:
>
>
>> Rajith Attapattu wrote:
>>
>>
>>> Jonathan, appologies if I wasn't clear enough.
>>>
>>> The goal was to replace the current documentaiton page at
>>> http://cwiki.apache.org/confluence/display/qpid/Documentation with the
>>> proposed
>>> http://cwiki.apache.org/confluence/display/qpid/DocumentationB
>>>
>>> The reason why I created a parallel page was for folks to compare the two
>>> and make decesion.
>>> Since this was a main page I didn't want to arbitarily reorganize it
>>> without
>>> getting any approval/feedback from the community.
>>>
>>>
>>>
>> Whew! I apologize for being stupid and alarmist here ;->
>>
>> I like your new page better, but I think we need sections by language,
>> showing the API guides and examples for each language.
>>
>
>
> If you click on a particular client, there is a link to the API guides (if
> available)
> Examples are listed as a top level link.
>
> I am not sure if there is a point in having sections by language, rather it
> should be by messaging client.
> After all the API guides that we have currenty are for the messaging
> clients.
>
> Now there will be API guides for QMF as well. Ex the python and c++ based
> API's.
> We need to make sure we distinguish properly between these API's and the
> messaging client API's
>
> Regards,
>
> Rajith
>
>
>
>> Jonathan
>>
>>
>> ---------------------------------------------------------------------
>> Apache Qpid - AMQP Messaging Implementation
>> Project: http://qpid.apache.org
>> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>>
>>
>>
>
>
>
Re: Qpid Documentation page
Posted by Jonathan Robie <jo...@redhat.com>.
Rajith Attapattu wrote:
> Now there will be API guides for QMF as well. Ex the python and c++ based
> API's.
> We need to make sure we distinguish properly between these API's and the
> messaging client API's
>
Currently, the Python console API is in the normal Python API docs. Is
there a reason not to do it that way?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Documentation page
Posted by Rajith Attapattu <ra...@gmail.com>.
On Wed, Feb 11, 2009 at 1:25 PM, Jonathan Robie
<jo...@redhat.com>wrote:
> Rajith Attapattu wrote:
>
>> Jonathan, appologies if I wasn't clear enough.
>>
>> The goal was to replace the current documentaiton page at
>> http://cwiki.apache.org/confluence/display/qpid/Documentation with the
>> proposed
>> http://cwiki.apache.org/confluence/display/qpid/DocumentationB
>>
>> The reason why I created a parallel page was for folks to compare the two
>> and make decesion.
>> Since this was a main page I didn't want to arbitarily reorganize it
>> without
>> getting any approval/feedback from the community.
>>
>>
>
> Whew! I apologize for being stupid and alarmist here ;->
>
> I like your new page better, but I think we need sections by language,
> showing the API guides and examples for each language.
If you click on a particular client, there is a link to the API guides (if
available)
Examples are listed as a top level link.
I am not sure if there is a point in having sections by language, rather it
should be by messaging client.
After all the API guides that we have currenty are for the messaging
clients.
Now there will be API guides for QMF as well. Ex the python and c++ based
API's.
We need to make sure we distinguish properly between these API's and the
messaging client API's
Regards,
Rajith
>
> Jonathan
>
>
> ---------------------------------------------------------------------
> 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/
Re: Qpid Documentation page
Posted by Jonathan Robie <jo...@redhat.com>.
Rajith Attapattu wrote:
> Jonathan, appologies if I wasn't clear enough.
>
> The goal was to replace the current documentaiton page at
> http://cwiki.apache.org/confluence/display/qpid/Documentation with the
> proposed
> http://cwiki.apache.org/confluence/display/qpid/DocumentationB
>
> The reason why I created a parallel page was for folks to compare the two
> and make decesion.
> Since this was a main page I didn't want to arbitarily reorganize it without
> getting any approval/feedback from the community.
>
Whew! I apologize for being stupid and alarmist here ;->
I like your new page better, but I think we need sections by language,
showing the API guides and examples for each language.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Documentation page
Posted by Rajith Attapattu <ra...@gmail.com>.
Jonathan, appologies if I wasn't clear enough.
The goal was to replace the current documentaiton page at
http://cwiki.apache.org/confluence/display/qpid/Documentation with the
proposed
http://cwiki.apache.org/confluence/display/qpid/DocumentationB
The reason why I created a parallel page was for folks to compare the two
and make decesion.
Since this was a main page I didn't want to arbitarily reorganize it without
getting any approval/feedback from the community.
Regards,
Rajith
On Wed, Feb 11, 2009 at 1:15 PM, Jonathan Robie
<jo...@redhat.com>wrote:
> Help! This is another page also claiming to be "the" documentation page.
> It's not what users will get if they click on the "Documentation" link on
> the left hand side.
>
> I really think we need to focus on what users get to if they click on the
> navigation links first. I've seen several pages that try to provide an
> independent overview of what's going on, and over time, these pages get
> abandoned and out of date. Top-down is good here. "The" documentation page
> is here:
>
> http://cwiki.apache.org/confluence/display/qpid/Documentation
>
> One good documentation page is better than a collection of documentation
> pages that differ in various ways.
>
> Jonathan
>
>
> Rajith Attapattu wrote:
>
>> Hi All,
>>
>> I had a stab at re organizing the Qpid documentation page.
>> Looking at dev/user list I found that several users had a bit of trouble
>> finding out the info they are looking for.
>>
>> The goals for the re-org are,
>> 1. Provide a top level index of documentation broken down by functional
>> area.
>> 2. Organize all relavent information in one location (Ex all user
>> guides/How
>> To's for JMS client under one location and not mix it up with broker docs)
>> 3. Try to make a clear separation between user guides vs developer
>> information.
>> 4. Build up a list of links/content that we need to maintain every release
>> ..etc
>>
>> http://cwiki.apache.org/confluence/display/qpid/DocumentationB
>>
>> The above link is work in progress and comments/suggestions are most
>> welcomed.
>> Once everybody is happy about the direction/content I would like to
>> replace
>> the current documentation page with the contents in the above link.
>>
>> 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
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
Re: Qpid Documentation page
Posted by Jonathan Robie <jo...@redhat.com>.
Help! This is another page also claiming to be "the" documentation page.
It's not what users will get if they click on the "Documentation" link
on the left hand side.
I really think we need to focus on what users get to if they click on
the navigation links first. I've seen several pages that try to provide
an independent overview of what's going on, and over time, these pages
get abandoned and out of date. Top-down is good here. "The"
documentation page is here:
http://cwiki.apache.org/confluence/display/qpid/Documentation
One good documentation page is better than a collection of documentation
pages that differ in various ways.
Jonathan
Rajith Attapattu wrote:
> Hi All,
>
> I had a stab at re organizing the Qpid documentation page.
> Looking at dev/user list I found that several users had a bit of trouble
> finding out the info they are looking for.
>
> The goals for the re-org are,
> 1. Provide a top level index of documentation broken down by functional
> area.
> 2. Organize all relavent information in one location (Ex all user guides/How
> To's for JMS client under one location and not mix it up with broker docs)
> 3. Try to make a clear separation between user guides vs developer
> information.
> 4. Build up a list of links/content that we need to maintain every release
> ..etc
>
> http://cwiki.apache.org/confluence/display/qpid/DocumentationB
>
> The above link is work in progress and comments/suggestions are most
> welcomed.
> Once everybody is happy about the direction/content I would like to replace
> the current documentation page with the contents in the above link.
>
> 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