You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@camel.apache.org by Martin Gilday <ma...@imap.cc> on 2008/04/16 11:57:42 UTC
Improving the documentation for novices
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.
Re: Improving the documentation for novices
Posted by Martin Gilday <ma...@imap.cc>.
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" <gl...@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.
Re: Improving the documentation for novices
Posted by Glen Mazza <gl...@gmail.com>.
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.
Re: Improving the documentation for novices
Posted by Jonathan Anstey <ja...@gmail.com>.
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.
>
Re: Improving the documentation for novices
Posted by James Strachan <ja...@gmail.com>.
On 16/04/2008, Martin Gilday <ma...@imap.cc> wrote:
> 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?
Yeah - its really to a make the simplest example with the simplest
dependencies. The direct: endpoint just depends on the camel-core.jar
so there's no need for a JMS provider, a message broker and all that
stuff which can cause confusion for beginners.
But loads of folks using Camel use JMS so having a good JMS tutorial
would really help folks do more real world stuff; once they've moved
beyond learning how to use EIP with Camel.
> 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?
Perfect. There's more details here...
http://activemq.apache.org/camel/contributing.html
but basically just raise a JIRA and attach some code (remember to
click the checkbox when you add your attachment that you are granting
the ASF use of the code etc). Then we can commit it and hopefully use
it as an integration test - as well as a tutorial and working example
folks can reuse.
> 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.
Great idea! :)
It definitely needs a bit of refactoring.
> 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.
Great stuff
> 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
Its a tad complex. This page might help a little...
http://activemq.apache.org/camel/how-does-the-website-work.html
basically caching means it takes a while to appear - though you can
usually check your updates at
http://cwiki.apache.org/CAMEL/
one extra complication is the generation of that static html sometimes
has bugs (i.e. some changes to included pages like navigation don't
always force the regeneration of the entire site). So I often kick off
a manual export to HTML from time to time.
--
James
-------
http://macstrac.blogspot.com/
Open Source Integration
http://open.iona.com
Re: Improving the documentation for novices
Posted by Martin Gilday <ma...@imap.cc>.
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" <ja...@gmail.com>
To: camel-dev@activemq.apache.org
Date: Wed, 16 Apr 2008 17:21:48 +0100
Subject: Re: Improving the documentation for novices
On 16/04/2008, Martin Gilday <ma...@imap.cc> 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
Re: Improving the documentation for novices
Posted by James Strachan <ja...@gmail.com>.
On 16/04/2008, Martin Gilday <ma...@imap.cc> 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
RE: Improving the documentation for novices
Posted by Claus Ibsen <ci...@silverbullet.dk>.
Hi Martin
This is an excellent tutorial you have started to write. This is really great that it starts from the top how to setup a project with pom.xml and its dependencies and all the stuff that can be tricky to get right at start.
And yes we would love a more elaborate example that doesn't just focus on tidy bits and bolts how to use a single component as they current ones mostly does.
Your tutorial is really a great giant leap to improve the documentation and understanding how to use Camel.
Please keep it coming. We will for sure help where we can with e.g. proof reading and including your hard work in the distribution.
Med venlig hilsen
Claus Ibsen
......................................
Silverbullet
Skovsgårdsvænget 21
8362 Hørning
Tlf. +45 2962 7576
Web: www.silverbullet.dk
-----Original Message-----
From: Martin Gilday [mailto:martin.lists@imap.cc]
Sent: 16. april 2008 11:58
To: camel-dev@activemq.apache.org
Subject: Improving the documentation for novices
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.