> 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
