camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Martin Gilday" <martin.li...@imap.cc>
Subject Re: Improving the documentation for novices
Date Sat, 19 Apr 2008 14:49:17 GMT
The "Developers" heading on the navigation menu already linked to the
same page as "Developer Guide" anyway so I've moved it into the same
section.


----- Original message -----
From: "Glen Mazza" <glen.mazza@gmail.com>
To: camel-dev@activemq.apache.org
Date: Sat, 19 Apr 2008 07:00:37 -0700 (PDT)
Subject: Re: Improving the documentation for novices


BTW, another suggestion, it may be good to move the "Developer Guide"
link on
the right-hand menu from the "Documentation" section to the "Developers"
section.  It can be confusing to Camel users, because they are also
developers (even if not Camel ones), and so may not be sure of the
difference between the "User Guide" and the "Developer Guide".

Regards,
Glen


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

-- 
View this message in context:
http://www.nabble.com/Improving-the-documentation-for-novices-tp16720261s22882p16783420.html
Sent from the Camel - Development mailing list archive at Nabble.com.


Mime
View raw message