From users-return-66899-archive-asf-public=cust-asf.ponee.io@camel.apache.org Thu Jan 18 23:10:21 2018 Return-Path: X-Original-To: archive-asf-public@eu.ponee.io Delivered-To: archive-asf-public@eu.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by mx-eu-01.ponee.io (Postfix) with ESMTP id 013D6180654 for ; Thu, 18 Jan 2018 23:10:21 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id E2045160C2B; Thu, 18 Jan 2018 22:10:20 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 328E1160C26 for ; Thu, 18 Jan 2018 23:10:20 +0100 (CET) Received: (qmail 7483 invoked by uid 500); 18 Jan 2018 22:10:14 -0000 Mailing-List: contact users-help@camel.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: users@camel.apache.org Delivered-To: mailing list users@camel.apache.org Received: (qmail 7464 invoked by uid 99); 18 Jan 2018 22:10:13 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 18 Jan 2018 22:10:13 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id 2E501C0299 for ; Thu, 18 Jan 2018 22:10:11 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -0.001 X-Spam-Level: X-Spam-Status: No, score=-0.001 tagged_above=-999 required=6.31 tests=[RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=disabled Received: from mx1-lw-us.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id 31gUCUma-Adi for ; Thu, 18 Jan 2018 22:10:02 +0000 (UTC) Received: from sender-of-o51.zoho.com (sender-of-o51.zoho.com [135.84.80.216]) by mx1-lw-us.apache.org (ASF Mail Server at mx1-lw-us.apache.org) with ESMTPS id A79F65F3F0 for ; Thu, 18 Jan 2018 22:10:01 +0000 (UTC) Received: from Bretts-MacBook-Pro.local (c-73-146-133-213.hsd1.in.comcast.net [73.146.133.213]) by mx.zohomail.com with SMTPS id 1516313392776770.3755215033299; Thu, 18 Jan 2018 14:09:52 -0800 (PST) Subject: Re: State of the current Camel wiki documentation To: users@camel.apache.org References: <3585d4fe-eb81-070d-8762-a98778158f6f@3riverdev.com> From: Brett Meyer Message-ID: Date: Thu, 18 Jan 2018 17:09:51 -0500 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:52.0) Gecko/20100101 Thunderbird/52.5.2 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Content-Language: en-US X-ZohoMailClient: External Pull requests are still a thing, right? ;) Kidding aside, the GitHub pull request and review process seems highly preferable to fighting the wonky Confluence platform, especially since it gives the community a chance to chat about proposed changes before they're merged. What about that is concerning?  And with the exception of the eventual merge/commit, why would that limit the documentation pool to committers only?  From my experience, the Camel committer team have always been incredibly quick to respond to and work through pull requests... On 1/18/18 5:00 PM, Paul Gale wrote: > Brett, > > Thanks for your response. > > You have confirmed my worst fears about the documentation solution. Oh > well, all those future edits I had in mind, gone. > Thanks, > Paul > > > On Thu, Jan 18, 2018 at 4:55 PM, Brett Meyer wrote: >> Hey Paul, I asked the same question a couple of weeks ago -- Claus reminded >> me about the move to asciidoc in the central repo: >> 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 >> >>