On 16/04/2008, Martin Gilday <[EMAIL PROTECTED]> wrote: > Hi, > > I have been working with Camel for a couple of weeks now and would like > to share my experiences of the documentation and learning curve. I have > found that the documentation is of a high standard and a very string > effort to ensure that all components are covered. The problem I had > with approaching it is that it is badly structured and hard to know what > to read first when you are a beginner.
Thanks for the great feedback BTW - its really hard knowing the right way to structure information when you already kinda know it :) > These problems have been > mentioned in the 'Book in One Page'. However I only found this after a > week, and once I did it really helped me understand Camel, as there is a > lot of good information in the opening section not found on the rest of > the site, and gives an ordering of what you need to know. > > Ideas we could try: > * Give more prominance to the 'Book in One Page'[1]. Place a link from > the home page to it, or list it on the side bar under the documentation > heading. FWIW the book in one page... http://activemq.apache.org/camel/book-in-one-page.html is really just this section of pages included in a single page to make the PDF thats in the 1.3.0 distro in the doc directory http://activemq.apache.org/camel/book.html pretty much all of the contents are just included from the documentation section http://activemq.apache.org/camel/documentation.html the main difference is that the User Guide section of that documentation... http://activemq.apache.org/camel/user-guide.html has a small getting started guide http://activemq.apache.org/camel/getting-started.html whereas the book has a different getting started guide... http://activemq.apache.org/camel/book-getting-started.html As a first cut to try fix this a bit, I've added links to this longer getting started guide to the user guide... http://cwiki.apache.org/CAMEL/user-guide.html I'm sure we can do better; maybe we should refactor the 2 getting started pages a bit more? > * Create a tutorial which shows an example Camel project whilst also > explaining how Camel works and its concepts while the user is writing > it. There are already a number of examples with explanations but they > are small and independent and for the most part assume the reader has > understood Camel architecture and terminology. I think by combining > examples with the architecture will help novices 'get' Camel quicker. Great idea! > I > have attempted to start such a tutorial [2] which guides a user through > creating a Camel request/reply project using Spring remoting. However > as I am really not a technical writer nor knowledgable about Camel it > still needs embellishing with what is happening at each stage. I do > think a reasonable outline is there of what I would like to have seen > when I first approached Camel. I would appreciate any additions, > corrections or feedback. Great stuff! :) I love contributions. I'll take a read and see if I can add anything. I guess we need a Tutorials section of the site somewhere... > > [1] http://activemq.apache.org/camel/book-in-one-page.html > [2] > http://cwiki.apache.org/confluence/display/CAMEL/Tutorial-JmsRemoting > > What do the Camel team think about these ideas? > > Thanks, > > Martin. > -- James ------- http://macstrac.blogspot.com/ Open Source Integration http://open.iona.com
