camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Claus Ibsen <claus.ib...@gmail.com>
Subject Re: 3.0 Ideas
Date Wed, 27 Mar 2013 06:57:41 GMT
On Mon, Mar 25, 2013 at 11:10 PM, Raul Kripalani <raul@evosent.com> wrote:
> Hi Claus,
>
> Responses inline.
>
> Regards,
>
> *Raúl Kripalani*
> Enterprise Architect, Open Source Integration specialist, Program
> Manager | Apache
> Camel Committer
> http://about.me/raulkripalani | http://www.linkedin.com/in/raulkripalani
> http://blog.raulkr.net | twitter: @raulvk
>
> On Mon, Mar 25, 2013 at 4:43 PM, Claus Ibsen <claus.ibsen@gmail.com> wrote:
>
>> On Sun, Mar 24, 2013 at 5:23 PM, Henryk Konsek <hekonsek@gmail.com> wrote:
>> >> We already have a removeHeaders() DSL [1]
>> >
>> > Wow, indeed we got it. :)
>> >
>> > We definitely need to improve our documentation in this regards. I
>> > feel pretty familiar with Camel wiki and haven't notice this one :) .
>> > I guess that the majority of our users don't know about removeHeaders
>> > option as well.
>> >
>> > I'll try to edit wiki to make this option more visible. Not sure when
>> however.
>> >
>>
>> Do you guys read the javadoc of the Java DSL? We have java doc on the
>> DSL where we provide a little information.
>>
>
> I know you aren't referring to me, but I'm sure that all dev@ posters have
> read the Javadocs ;)
>
>
>> We could enhance this javadoc and add more links to more details at
>> the Camel web site. For example in the case of removeHeader DSL we
>> could refer to these FAQ's etc.
>>
>
> You're just asking for broken links in the Javadocs! We can't guarantee
> that a FAQ entry will be alive for the lifetime of a Camel release in the
> Maven repos, i.e. forever.
>

The FAQ entries have been online for 6 years and they have not been broken.
The links is static and stable.

For example this old FAQ
http://camel.apache.org/can-i-use-camel-on-java-14.html

We should give the end users hints and references where they can read
more material.
If they use Java DSL then javadoc is the standard in Java, how to
document an API.

We already have javadoc for the Java DSL. It would be easy to add some
more material in these javadocs,
and as well point the users to FAQs, and the EIP docs etc.


> IMHO we should focus on restructuring the website (see below). Let's fix
> the base problem instead of patching here and there and creating a jumble
> of unmaintainable links throughout time.
>
> Improving docs is always appreciated. For example at any time fell
>> free to add FAQ entries for stuff that you feel is good knowledge for
>> others.
>

I was maybe not to precise in the mail. I was suggesting to add FAQs
for stuff that you
see as common questions that people keep asking about in these forums.

And you are allowed to use what you have between your ears, and add /
improve the docs.
So if one of the EIPs could be improved, then for sure fell free to
work on that doc page as well.

Frankly its not very many of the Camel team members who help with the
docs. I don't blame them.
Its probably more fun to work on the code.

Another way to help our end users is to build new examples, as often
an example is a great way of learning stuff.

Or even add a little new cookbook snippet about how to do X
http://camel.apache.org/cookbook



>
> I beg to differ. FAQ-centric documentation is hell for everyone:
> committers, users, evaluators, newbies, etc. Imagine if Wikipedia was a
> collection of a bunch of questions like "When was the GMT timezone
> created?", "How tall can a Giraffe be?", etc. You get me.
>

First I think your wikipedia analogy is off - And I do NOT get you.

The first thing I do on wikipedia, is to type in a key word(s) to
search for links what I am looking for. That is similar to what you
can do on the Camel site with the "search box" Whether those "hits"
refer to a FAQ, or other places does not matter. Its the fact we have
hit on links where the user can read more.

Frankly all/most OSS projects have FAQs (and with more content we do).
See for example Apache Tomcat
http://wiki.apache.org/tomcat/FAQ
http://wiki.apache.org/tomcat/HowTo

The FAQ should not be the single-source of information. But where we
can have a short description and point the readers to other pages
where he/she can find more material. So its just a help for the users.

And also a way of telling users what are some of the common "stuff"
that people have with Camel.

Frankly you guys should try look at our FAQ, there may be stuff you do not know.
And also can inspire you to say .. ah I see this problem/question
alot, but I cannot find a FAQ for it. Let me add that.


> We need better documentation structure. I shared some ideas on overhauling
> component pages in May 2012 [1] - before I became a committer. But the need
> for a modern website keeps haunting me time after time, as I see other
> sites like Apache Cordova [2], Apache Shiro [3], etc. Even the Apache ODE
> project [4] – which hasn't seen a release in 2 years – has a refurbished
> website!
>
> All in all: new website, new documentation structure.
>

Well guess what. Of all the zillion Camel 3.0 ideas, you are the only
one raising that task.
Again most of the Camel committers want to hack on the camel-core code.

Dont take me wrong. I would like a revamped website, and top notch
documentation.
But that is very hard to do, and takes a long time.

There is a ton of Camel documentation. Its just a mix between
- Camel wiki pages
- 3rd party blogs, articles, tutorials (links from our articles page)
- Camel in Action book
- Video presentations
- etc



> I guess I'm asking to reignite the discussion here: [5].
>
> [1]
> http://camel.465427.n5.nabble.com/Improving-the-Documentation-Articles-Presentations-etc-tp5711559p5713170.html
> [2] http://cordova.apache.org/
> [3] http://shiro.apache.org/
> [4] http://ode.apache.org/
> [5] http://camel.apache.org/site-update-ideas.html
>
>
>>
>> --
>> Claus Ibsen
>> -----------------
>> Red Hat, Inc.
>> FuseSource is now part of Red Hat
>> Email: cibsen@redhat.com
>> Web: http://fusesource.com
>> Twitter: davsclaus
>> Blog: http://davsclaus.com
>> Author of Camel in Action: http://www.manning.com/ibsen
>>



-- 
Claus Ibsen
-----------------
Red Hat, Inc.
FuseSource is now part of Red Hat
Email: cibsen@redhat.com
Web: http://fusesource.com
Twitter: davsclaus
Blog: http://davsclaus.com
Author of Camel in Action: http://www.manning.com/ibsen

Mime
View raw message