On Fri, Feb 13, 2009 at 4:05 AM, Marnie McCormack < marnie.mccorm...@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 <rafa...@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-subscr...@qpid.apache.org > > > > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/
