Martin Gilday 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. 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.
Case in point: I never knew this page existed :)
Sounds like a good idea to me.
* 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. 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.
Thats a great start Martin. I guess whenever the tutorial example is
done we can include it as an example in Camel? Then we can refer the
wiki doc to real code snippets so it doesn't get out of sync with the code.
[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.
