camel-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrea Cosentino <>
Subject Re: Re: State of the current Camel wiki documentation
Date Fri, 19 Jan 2018 06:56:02 GMT
You won't have to wait for a new release of Camel to see the site updated. The documentation
will go live, as the site of confluence was.

In that way you'll have the actual Snapshot documentation always updated. Once we released
a version, the documentation will be freezed as that version docs.

This is the idea.

By the way, at the time of moving the docs, there were discussion about this.

Andrea Cosentino 
Apache Camel PMC Member
Apache Karaf Committer
Apache Servicemix PMC Member
Twitter: @oscerd2
Github: oscerd

On Friday, January 19, 2018, 7:46:44 AM GMT+1, Paul Gale <> wrote:

Funny that, I never had any problems editing the wiki. Not that I'm
not endorsing the old tooling - it could have have been much improved.
However, despite not being the most pleasant system to use it didn't
prevent me from doing the work. What's more any edits I made would
show up on the wiki within a couple of hours, I didn't have to wait
until the next dot release of Camel for the site to be updated, which
could be weeks or months away. Version control tools were around a
long before the wiki was invented by Ward Cuningham. One of the
reasons why wikis became as popular as they did was precisely because
they were divorced from the traditional version control based methods
used up to that point based and yet made it easier to manage the
versioning of the content in a more immediate and democratized way.

I believe that the fact that it was out of sync had nothing to do with
the fact that it was in a separate repo (as it were). I realize that
the belief that it was the cause was widely held, however, the problem
was misdiagnosed. There's nothing inherent in the new structure that
would prevent the situation of a component being modified, say, and
the documentation not being updated. The documentation could, perhaps,
be viewed as a separately versioned artifact that the source repo
might reference in its packaging, although that's still suffers from
some of the same problems.

On Fri, Jan 19, 2018 at 12:51 AM, Andrea Cosentino
<> wrote:
> The only thing to consider here is that having a site separated from repo with docs never
really worked and it's ALWAYS out of sync.
> Inviato da Yahoo Mail su Android
>  Il ven, 19 gen, 2018 alle 2:00, Paul Gale<> ha scritto: 
>I generally agree that the documentation should be part of the code otherwise it is out
of alignment.
> If by 'alignment' you mean that the doc is correct with regard to the
> source it shipped with can be inferred because they came from the same
> repo/commit? If so that doesn't make sense to me.
> Ensuring alignment, as it were, requires additional correlating
> metadata which does not require that they both live in the same repo.
> When they're in different repos that affords one the ability to have
> separate and distinct management strategies for each, e.g., being able
> to relax the requirement of PRs for documentation.
> Thanks,
> Paul
> On Thu, Jan 18, 2018 at 6:32 PM, Owain McGuire
> <> wrote:
>> Paul,
>> 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?
>> O.
>>> 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 <>
>>>>>> 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
>>>>>> current
>>>>>> Confluence docs (assuming there's a way to do that without editing
>>>>>> single page) mentioning the stale state and future plans.  Better
>>>>>> could
>>>>>> we consider setting up a redirect sooner rather than later, even
>>>>>> 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
>>>>>>> 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
>>>>>>> explain the breakage. However, I don't know where they should
>>>>>>> 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
>>>>>>> see any reference to them in the Atlassian documentation. Perhaps
>>>>>>> support came from a plugin that's no longer installed? Guessing.
>>>>>>> info about that would also be appreciated.
>>>>>>> I understand that the current Confluence backed wiki is generated
>>>>>>> some scheduled process. Can that process itself be documented
>>>>>>> access to it granted to the entire community? I would have thought
>>>>>>> opening up access would increase the likelihood of it getting
>>>>>>> I've edited a number of pages on both the ActiveMQ and Camel
>>>>>>> however I am not a committer (and have no plans to become one)
>>>>>>> therefore cannot step in to fix it when it breaks.
>>>>>>> I recall hearing plans that Confluence would be replaced by some
>>>>>>> documentation, perhaps a wiki on Github (ugh). What's the latest
>>>>>>> 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 a
>>>>>>> requirement would be unacceptable to me. However, it seems to
>>>>>>> likely based on the solutions I've heard proposed elsewhere (assuming
>>>>>>> the Camel community follows suite with the ActiveMQ community
>>>>>>> appear set on such an approach - reasonable assumption given
>>>>>>> overlap between the respective communities) that documentation
>>>>>>> embedded in the sourcecode, extracted using a tool that would
>>>>>>> generate the site, or something similar. Any approach along those
>>>>>>> lines would likely reduce the pool size of available wiki editors
>>>>>>> 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
>>>>>>> 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