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 <paul.n.g...@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
>>>>
>>>>
>>>>
>>
>>
