camel-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Owain McGuire <>
Subject Re: State of the current Camel wiki documentation
Date Thu, 18 Jan 2018 23:32:27 GMT

One of the hardest aspects of using Camel is the ability to read the documentation.  We generally
use “pair-reading” to interpret unfamiliar areas - reviewing the examples, tests and source
code are more productive.  I generally agree that the documentation should be part of the
code otherwise it is out of alignment.  However, a wiki ethos seems more alive to me.  Pull
requests seem too heavy as you say.  

Are we really talking about the need for a User Guide Wiki, somewhere between adoc and the
“books”.  Is there a place for a Cookbook of example routes with pointers to the “hard”
docs to aid adoption?

In the back of my mind I think there could be something like a library of “lego routes”
which are working routes on Github that use components to do real life examples using components
and EIPs.  e.g. pick up a message and send to slack, pull an order from Amazon Marketplace,
raise an order in Netsuite.  The exchange architecture of properties and headers which are
propagated provide a mechanism to have very late binding on route endpoints.  Morph into RAAS
(Routes as a Service)?  TNBT??  Perhaps a step too far at the moment but something to counter
the “clicks v code” objections I get from customers.   How far has Mulesoft pushed this?


> On 18 Jan 2018, at 22:44, Paul Gale <> wrote:
> Trust me, I have no love for Confluence as a product. However, even
> with only editor rights I could work completely autonomously when it
> came to editing the documentation. The ease with which I could update
> the documentation made me all the more willing to do so, even for
> simple typos and reformatting, nevermind correcting horrific grammar.
> To have that same ability in the new scheme would require committer
> rights. Going through a pull-request process for documentation is
> antithetical to the egalitarian nature of a wiki. The responsiveness
> of committers to accepting a pull requests is beside the point; if
> they're accepting said requests by reflex then they're not adding any
> value so why have them in the loop. Now, however, I will hesitate
> before considering an edit which more often than not will result in it
> being abandoned - it's just human nature. However, on the ActiveMQ
> wiki, for example, I rewrote/reformatted/reworked whole pages that
> were out of date, on a few occasions spending days doing so. Such
> large scale edits, in contrast to a minor correction, increase the
> likelihood of either push back or rejection if they have to submitted
> through an approval process. The irony of such changes being approved
> by the very people whose initial offering is being reworked is not
> lost on me. Any errors in content I may/will make can easily be fixed
> by another editor making a correction of their own. That's a more
> effective way to work than a gated approval process. All part of the
> wiki concept I suppose.
> Regardless, this situation can be avoided if the documentation is
> managed like a wiki and made open to the general public for editing.
> Can that be done?
> Thanks,
> Paul
> On Thu, Jan 18, 2018 at 5:09 PM, Brett Meyer <> wrote:
>> Pull requests are still a thing, right? ;)
>> Kidding aside, the GitHub pull request and review process seems highly
>> preferable to fighting the wonky Confluence platform, especially since it
>> gives the community a chance to chat about proposed changes before they're
>> merged.
>> What about that is concerning?  And with the exception of the eventual
>> merge/commit, why would that limit the documentation pool to committers
>> only?  From my experience, the Camel committer team have always been
>> incredibly quick to respond to and work through pull requests...
>> On 1/18/18 5:00 PM, Paul Gale wrote:
>>> Brett,
>>> Thanks for your response.
>>> You have confirmed my worst fears about the documentation solution. Oh
>>> well, all those future edits I had in mind, gone.
>>> Thanks,
>>> Paul
>>> On Thu, Jan 18, 2018 at 4:55 PM, Brett Meyer <> wrote:
>>>> Hey Paul, I asked the same question a couple of weeks ago -- Claus
>>>> reminded
>>>> me about the move to asciidoc in the central repo:
>>>> However, we might consider at least adding a note to the tops of the
>>>> current
>>>> Confluence docs (assuming there's a way to do that without editing every
>>>> single page) mentioning the stale state and future plans.  Better yet,
>>>> could
>>>> we consider setting up a redirect sooner rather than later, even if
>>>> that's
>>>> temporarily to GitHub (maybe
>>>> On 1/18/18 4:34 PM, Paul Gale wrote:
>>>>> Can someone with the relevant privileges investigate why snippets
>>>>> being referenced by the Camel wiki appear to be universally broken and
>>>>> what can be done to fix them? They are an integral part of the
>>>>> documentation and need to work. At a glance I can see that most
>>>>> snippets reference source files from an SVN repository which would
>>>>> explain the breakage. However, I don't know where they should point
>>>>> instead as removing the word 'trunk' in the file path doesn't fix it.
>>>>> It would seem that snippet support is no longer available - I don't
>>>>> see any reference to them in the Atlassian documentation. Perhaps said
>>>>> support came from a plugin that's no longer installed? Guessing. Any
>>>>> info about that would also be appreciated.
>>>>> I understand that the current Confluence backed wiki is generated via
>>>>> some scheduled process. Can that process itself be documented and
>>>>> access to it granted to the entire community? I would have thought
>>>>> opening up access would increase the likelihood of it getting fixed.
>>>>> I've edited a number of pages on both the ActiveMQ and Camel wikis,
>>>>> however I am not a committer (and have no plans to become one) and
>>>>> therefore cannot step in to fix it when it breaks.
>>>>> I recall hearing plans that Confluence would be replaced by some other
>>>>> documentation, perhaps a wiki on Github (ugh). What's the latest on
>>>>> that front?
>>>>> I do hope that whatever solution is settled on does not require one to
>>>>> be an Apache committer in order to edit the wiki documentation. Such
>>>>> requirement would be unacceptable to me. However, it seems to be
>>>>> likely based on the solutions I've heard proposed elsewhere (assuming
>>>>> the Camel community follows suite with the ActiveMQ community who
>>>>> appear set on such an approach - reasonable assumption given the
>>>>> overlap between the respective communities) that documentation be
>>>>> embedded in the sourcecode, extracted using a tool that would then
>>>>> generate the site, or something similar. Any approach along those
>>>>> lines would likely reduce the pool size of available wiki editors to
>>>>> just those with commit rights. Given that committers have openly
>>>>> stated their reluctance/dislike/opposition to ever writing
>>>>> documentation then such solutions seem unwise and detrimental to the
>>>>> community as a whole. I'm not convinced by the logic used to justify
>>>>> these solutions that because the documentation is inline with the code
>>>>> that it's more likely to be kept up to date and accurate. I therefore
>>>>> strongly urge the community to reconsider.
>>>>> Thanks,
>>>>> Paul

View raw message