Thanks for the positive feedback guys. The TODOs are there are my short term goals of where I think I can take it. I tried to make something semi-realistic by using JMS, as a lot of samples just use "direct" to "direct" routes. I assume this is simply for ease of writing the sample tests, as unless I am missing something you would never really bother doing that?
I think Jonathan's idea of getting the tutorial code in the svn repo is a good, otherwise they are going to get out of sync pretty quickly if I keep attaching new zip files. What is the best way to do this? Should I create a JIRA task so a committer can put it somewhere? James I think your restructuring of the user guide is a step in the right direction. However I think it might be worth it if I try hacking at merging the two getting starting guides. The short one is too short being just a simple list of what you need to know, and should probably just be on the user guide page itself. Then I can rework the longer guide. I think I will move the critque of the docs to a new page and then move some of the general "how to read the docs" info to be an introduction to the user guide. This should keep each part focussed on the topic. I've tried updating the navigation bar [1] to include tutorials but it had no affect on the home page. Is there somewhere else I need to change or is it just caching? [1]http://cwiki.apache.org/confluence/display/CAMEL/Navigation ----- Original message ----- From: "James Strachan" <[EMAIL PROTECTED]> To: [email protected] Date: Wed, 16 Apr 2008 17:21:48 +0100 Subject: Re: Improving the documentation for novices 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
