State of the current Camel wiki documentation

[Paul Gale <pa...@gmail.com>]

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 a
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

Re: State of the current Camel wiki documentation

[Andrea Cosentino <an...@yahoo.com.INVALID>]

I don't know what it is your problem with PRs. Camel is a project where all the PRs are processed in small amount of time and also we aren't pedantic. All the PRs are generally accepted and merged in a few days. There is no need for relaxing about PRs. 

Also on confluence, we don't have any kind of control on what it is done and where. We just see an email with the info about a new build of the site. With PRs we can have much control on where we are in shape and where we need improvements.

Moving docs from confluence site to git repo was a big effort.

--
Andrea Cosentino 
----------------------------------
Apache Camel PMC Member
Apache Karaf Committer
Apache Servicemix PMC Member
Email: ancosen1985@yahoo.com
Twitter: @oscerd2
Github: oscerd






On Friday, January 19, 2018, 2:00:53 AM GMT+1, Paul Gale <pa...@gmail.com> wrote: 





>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
<ow...@integration.technology> 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 <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>>
>>>>> 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
>>>>>
>>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>>
>>>>>
>>>>>
>>>>> 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 a
>>>>>> 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
>>>>>
>>>>>
>>>>>
>>>
>>>
>

Re: Re: State of the current Camel wiki documentation

[Paul Gale <pa...@gmail.com>]

>By the way, at the time of moving the docs, there were discussion about this.
This may very well be moot, or rather closing the door after the horse
has bolted. However, I wasn't active at that time.

Plus my experience with such matters is that as I'm not a committer I
don't really get a say or cast a vote, so I doubt it would have much
difference.

>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.
So it seems that the result is a poor man's wiki. I should be able and
encouraged to make whatever edits I so wish without the need for prior
approval. The wiki model of 'consensus over credentials' is what
ensures the model works and that errors, mistakes or worse are at most
temporary.

Thanks,
Paul


On Fri, Jan 19, 2018 at 1:56 AM, Andrea Cosentino
<an...@yahoo.com.invalid> wrote:
> 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
> Email: ancosen1985@yahoo.com
> Twitter: @oscerd2
> Github: oscerd
>
>
>
>
>
>
> On Friday, January 19, 2018, 7:46:44 AM GMT+1, Paul Gale <pa...@gmail.com> 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.
> Thanks,
> Paul
>
>
> On Fri, Jan 19, 2018 at 12:51 AM, Andrea Cosentino
> <an...@yahoo.com.invalid> 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<pa...@gmail.com> 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
>> <ow...@integration.technology> 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 <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>>>>
>>>>>>> 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
>>>>>>>
>>>>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> 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 a
>>>>>>>> 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
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>
>>>>>
>>>

Re: Re: State of the current Camel wiki documentation

[Andrea Cosentino <an...@yahoo.com.INVALID>]

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
Email: ancosen1985@yahoo.com
Twitter: @oscerd2
Github: oscerd






On Friday, January 19, 2018, 7:46:44 AM GMT+1, Paul Gale <pa...@gmail.com> 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.
Thanks,
Paul


On Fri, Jan 19, 2018 at 12:51 AM, Andrea Cosentino
<an...@yahoo.com.invalid> 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<pa...@gmail.com> 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
> <ow...@integration.technology> 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 <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>>>
>>>>>> 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
>>>>>>
>>>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>>>
>>>>>>
>>>>>>
>>>>>> 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 a
>>>>>>> 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
>>>>>>
>>>>>>
>>>>>>
>>>>
>>>>
>>

Re: Re: State of the current Camel wiki documentation

[Paul Gale <pa...@gmail.com>]

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.
Thanks,
Paul


On Fri, Jan 19, 2018 at 12:51 AM, Andrea Cosentino
<an...@yahoo.com.invalid> 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<pa...@gmail.com> 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
> <ow...@integration.technology> 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 <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>>>
>>>>>> 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
>>>>>>
>>>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>>>
>>>>>>
>>>>>>
>>>>>> 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 a
>>>>>>> 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
>>>>>>
>>>>>>
>>>>>>
>>>>
>>>>
>>

R: Re: State of the current Camel wiki documentation

[Andrea Cosentino <an...@yahoo.com.INVALID>]

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<pa...@gmail.com> 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
<ow...@integration.technology> 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 <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>>
>>>>> 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
>>>>>
>>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>>
>>>>>
>>>>>
>>>>> 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 a
>>>>>> 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
>>>>>
>>>>>
>>>>>
>>>
>>>
>  

Re: State of the current Camel wiki documentation

[Paul Gale <pa...@gmail.com>]

>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
<ow...@integration.technology> 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 <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>>
>>>>> 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
>>>>>
>>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>>
>>>>>
>>>>>
>>>>> 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 a
>>>>>> 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
>>>>>
>>>>>
>>>>>
>>>
>>>
>

Re: State of the current Camel wiki documentation

[Owain McGuire <ow...@integration.technology>]

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 <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>> 
>>>> 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
>>>> 
>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>> 
>>>> 
>>>> 
>>>> 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 a
>>>>> 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
>>>> 
>>>> 
>>>> 
>> 
>> 

Re: State of the current Camel wiki documentation

[Paul Gale <pa...@gmail.com>]

>> No, it would not.  It would require a pull request.
A committer can commit without approval, no? That's the scenario I was
referring to in the case of documentation. At no point in the old
scheme did an edit require approval via a PR.

>Take a moment and actually look at https://github.com/apache/camel/pulls.  Note there are only 10 open PRs and a massive amount that were accepted.  For a project the size of Camel, that's an enormous accomplishment and a testament to the community/team.  The new documentation approach fits well within that.

I was talking about the documentation, not the sourcecode. Regardless,
if so few PRs are rejected then it proves that the folks making pull
requests need not be scrutinized.  ;)

>So, your primary frustration/worry is based on some misguided "ownership" concept and the assumption that others involved in that doc may take offense to changes?
No. At least I've not seen that happen.

I've not yet heard a defense of the PR mechanism for documentation (or
in general for that matter). What I've read so far are wonderful
accolades, admiration and testimony, not reasons why we shouldn't
abandon PRs for documentation. Why not try an extended experiment and
see what happens? If the honor/trust system fails we'll soon know.
When/if it does then offenders can be dealt with individually without
the need to supervise the majority to have them conform.

>Most project maintainers, myself included, would trip over themselves to help contributors interested in re-writing docs that we ourselves wrote
So the help I want is to have the PR mechanism for doc removed. Interested?

>Plus, how is that any different than contributing changes to *code* that someone else originally wrote?
It isn't. However, I thought that suggesting no PRs for code might be
a bridge too far and would cause heads to explode and Apache wonks to
have a hissy fit.

Thanks,
Paul


On Thu, Jan 18, 2018 at 6:09 PM, Brett Meyer <br...@3riverdev.com> wrote:
>> To have that same ability in the new scheme would require committer
>> rights.
>
> No, it would not.  It would require a pull request.
>
>> if they're accepting said requests by reflex then they're not adding any
>> value so why have them in the loop
>
> They're not.  I don't think I've ever seen anyone on the Camel team do
> anything "by reflex".
>
>> an edit which more often than not will result in it being abandoned
>
> Take a moment and actually look at https://github.com/apache/camel/pulls.
> Note there are only 10 open PRs and a massive amount that were accepted.
> For a project the size of Camel, that's an enormous accomplishment and a
> testament to the community/team.  The new documentation approach fits well
> within that.
>
>> The irony of such changes being approved by the very people whose initial
>> offering is being reworked is not lost on me.
>
> So, your primary frustration/worry is based on some misguided "ownership"
> concept and the assumption that others involved in that doc may take offense
> to changes?  I don't think you'll find that to be the case in most projects,
> especially in Camel.  Most project maintainers, myself included, would trip
> over themselves to help contributors interested in re-writing docs that we
> ourselves wrote.  Plus, how is that any different than contributing changes
> to *code* that someone else originally wrote?
>
>
> On 1/18/18 5:44 PM, 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 <br...@3riverdev.com> 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 <br...@3riverdev.com>
>>>> 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:
>>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>>
>>>>> 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
>>>>>
>>>>>
>>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>>
>>>>>
>>>>>
>>>>> 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 a
>>>>>> 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
>>>>>
>>>>>
>>>>>
>>>
>

Re: State of the current Camel wiki documentation

[Brett Meyer <br...@3riverdev.com>]

 > To have that same ability in the new scheme would require committer 
rights.

No, it would not.  It would require a pull request.

 > if they're accepting said requests by reflex then they're not adding 
any value so why have them in the loop

They're not.  I don't think I've ever seen anyone on the Camel team do 
anything "by reflex".

 > an edit which more often than not will result in it being abandoned

Take a moment and actually look at 
https://github.com/apache/camel/pulls.  Note there are only 10 open PRs 
and a massive amount that were accepted.  For a project the size of 
Camel, that's an enormous accomplishment and a testament to the 
community/team.  The new documentation approach fits well within that.

 > The irony of such changes being approved by the very people whose 
initial offering is being reworked is not lost on me.

So, your primary frustration/worry is based on some misguided 
"ownership" concept and the assumption that others involved in that doc 
may take offense to changes?  I don't think you'll find that to be the 
case in most projects, especially in Camel.  Most project maintainers, 
myself included, would trip over themselves to help contributors 
interested in re-writing docs that we ourselves wrote.  Plus, how is 
that any different than contributing changes to *code* that someone else 
originally wrote?

On 1/18/18 5:44 PM, 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>
>>>> 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
>>>>
>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>
>>>>
>>>>
>>>> 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 a
>>>>> 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
>>>>
>>>>
>>

Re: State of the current Camel wiki documentation

[Claus Ibsen <cl...@gmail.com>]

Hi

You can easily edit the docs online on github, just selected the
documentation file, and click the edit button and it has an in-place
editor, and when you save it creates a PR.
When you do so, then on top of github you should see something along
the lines of

You’re editing a file in a project you don’t have write access to.
We’ve created a fork of this project for you to commit your proposed
changes to. Submitting a change to this file will write it to a new
branch in your fork, so you can send a pull request.



On Thu, Jan 18, 2018 at 11:44 PM, Paul Gale <pa...@gmail.com> 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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>>
>>>> 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
>>>>
>>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>>
>>>>
>>>>
>>>> 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 a
>>>>> 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
>>>>
>>>>
>>>>
>>
>>



-- 
Claus Ibsen
-----------------
http://davsclaus.com @davsclaus
Camel in Action 2: https://www.manning.com/ibsen2

Re: State of the current Camel wiki documentation

[Paul Gale <pa...@gmail.com>]

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 <br...@3riverdev.com> 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 <br...@3riverdev.com> 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:
>>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>>
>>> 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
>>>
>>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>>
>>>
>>>
>>> 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 a
>>>> 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
>>>
>>>
>>>
>
>

Re: State of the current Camel wiki documentation

[Brett Meyer <br...@3riverdev.com>]

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 <br...@3riverdev.com> 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:
>> https://github.com/apache/camel/tree/master/docs/user-manual/en
>>
>> 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
>> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>>
>>
>>
>> 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 a
>>> 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
>>
>>

Re: State of the current Camel wiki documentation

[Paul Gale <pa...@gmail.com>]

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 <br...@3riverdev.com> 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:
> https://github.com/apache/camel/tree/master/docs/user-manual/en
>
> 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
> https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?
>
>
>
> 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 a
>> 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
>
>
>

Re: State of the current Camel wiki documentation

[Brett Meyer <br...@3riverdev.com>]

Hey Paul, I asked the same question a couple of weeks ago -- Claus 
reminded me about the move to asciidoc in the central repo: 
https://github.com/apache/camel/tree/master/docs/user-manual/en

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 
https://github.com/apache/camel/blob/master/docs/user-manual/en/SUMMARY.md)?


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 a
> 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