BTW - I realise I addressed Kai in the greeting, but when I say "you", I
mean the entire dev community :D
So please share your thoughts whenever you get a chance!
On 21 May 2012, at 21:48, Raul Kripalani <r...@fusesource.com> wrote:
Hi Kai,
Nice to meet you - being seeing lot of your work around ;)
Overhauling the Camel docs has also been in my mind for the past few days,
so I just wanted to share my thoughts and collaborate in the adventure. Camel
is a simple yet very powerful framework, but the docs don't really help to
get a jumpstart. I see this a lot with newbies. There's some lack of
structure, but that's a positive side effect of the massive growth in
Camel's traction!
What do you think about the following?
- Make the Architecture page a bit more concise, with links to expand.
Right now it's a big list of features, many of which don't relate to the
architecture. It could be quite confusing. You may end up thinking that the
Bean Language is part of the architecture, because it's the first link on a
bulleted list - that's where your eyes go immediately!
- As a newbie, I'd expect to see the bottom diagram at the top and an
explanation of the core concepts right on that page (rather than links).
- Getting Started => the fact that the first line of getting
started collaterally suggests downloading the source sounds daunting :D (a
guy who wants to download the source will search for it explicitly). The
"Longer Getting Started" looks more suited but it's too heavy to throw on
to a newbie. It needs freshness and a clear process. I expect a Getting
Started page to say: do this, now that, now this; instead of: follow this
link to learn more, and now this one, etc.
- Homogeneously structured component pages
- Quick reference table at the top with the following info: component
name, description, available since version, producer/consumer endpoints?,
prefixes, Maven dependency snippet
- ... followed by a table of contents (generated by Confluence)
- Main sections for each component page: URI format, options
reference, common features, producer-only features,
consumer-only features.
All component pages should follow the same sequence.
- Since Camel doesn't impose a particular data format, it's confusing
for newcomers to what data types each component can process, what type
converters it provides, etc. I suggest including a section for this.
I have many more ideas and I'm more than happy to work on all this stuff.
But before I start, I'd appreciate some feedback and, of course, your two
cents!
Also, how would you feel about re-designing the site? Take a look at the
landing pages of Apache Cassandra or Apache CouchDB. They're awesome and
user-friendly.
P.S.: Cross-posting to dev@ so we can continue discussing there. You may
remove users@ when you reply.
Regards,
*Raúl Kripalani*
Principal Consultant | FuseSource Corp.
r...@fusesource.com | fusesource.com <http://www.fusesource.com/>
skype: raul.fuse | twitter: @raulvk <http://twitter.com/raulvk>,
@fusenews<http://twitter.com/fusenews>
<http://twitter.com/fusenews>
On 21 May 2012 17:24, megachucky <megachu...@googlemail.com> wrote:
> Today, I had some time to add some structure to the articles. I am not
> really
> happy yet (because as Claus mentioned several articles are really old and
> outdated - so the release date of articles is also important), I will
> improve this when I find some more time. However, I think even the better
> structure helps new users a lot!
>
> https://cwiki.apache.org/confluence/display/CAMEL/Articles
>
> One more thing: I structured into "introductory", "advanced",
> "non-english",
> and some more. I think that there should be ONE starting point for new
> users
> which is up-to-date and explains all important Camel concepts with an
> example and code available to download. Therefore, there is one article at
> the beginning which is recommended for beginners due to these reasons. This
> article is not just a blog post, but more professional and reviewed by
> Claus
> because it was planned for InfoQ. It is from 2012 and offers source code at
> github.
> However, I want to mention that I have written this article :-) So feel
> free
> to add another article for the first one, if you know a better up-to-date
> introduction to Camel...
>
> -----
> Best regards,
> Kai Wähner
>
> Twitter: @KaiWaehner
> Email: kont...@kai-waehner.de
> Blog: www.kai-waehner.de/blog
> --
> View this message in context:
> http://camel.465427.n5.nabble.com/Improving-the-Documentation-Articles-Presentations-etc-tp5711559p5713033.html
> Sent from the Camel - Users mailing list archive at Nabble.com.
>
