camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Martin Gilday" <martin.li...@imap.cc>
Subject Improving the documentation for novices
Date Wed, 16 Apr 2008 09:57:42 GMT
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.
* 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.

[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.

Mime
View raw message