impala-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jim Apple <jbap...@cloudera.com>
Subject Re: Location of developers documentation
Date Thu, 21 Jul 2016 03:50:26 GMT
With my Cloudera hat on, I noticed that I can't share docs with the
whole world from my cloudera.com Google account. It's possible others
are in the same boat and will need to make special Google accounts
just to comment on docs even when contributing under the umbrella of
their employer. However, getting a duplicate Google account to write
and share docs may be no more laborious than getting an account on the
Apache Impala wiki.

On Wed, Jul 20, 2016 at 4:32 PM, Marcel Kornacker <marcel@cloudera.com> wrote:
> As far as I know, you can give edit rights to anyone with the link.
>
> On Wed, Jul 20, 2016 at 4:30 PM, Henry Robinson <henry@cloudera.com> wrote:
>> Google docs only work in my opinion if the following are true:
>>
>> 1. People who want to read and comment on them can do so without requesting
>> permission
>> 2. Ownership is not tied to one person, so that if someone stops
>> contributing to Impala, the rest of the contributors can still make changes
>> to the document as needed.
>>
>> Is that the case for google docs?
>>
>> On 20 July 2016 at 16:18, Marcel Kornacker <marcel@cloudera.com> wrote:
>>
>>> I meant this really for documents where we expect a good amount of
>>> discussion. Design docs and proposals are certainly in that category.
>>>
>>> Is there anything in that category that you would like to exclude?
>>>
>>> On Wed, Jul 20, 2016 at 3:35 PM, Jim Apple <jbapple@cloudera.com> wrote:
>>> > I think that's overkill. There are few documents that don't need
>>> > comments (I really tried to come up with one. Something written in
>>> > Linear A?)
>>> >
>>> > I also don't think Google docs are really ideal for a shared,
>>> > long-lived document managed by a diverse community.
>>> >
>>> > 1. The revision history tooling is weak.
>>> >
>>> > 2. Contributors have to be granted write access to docs one doc at a
>>> time.
>>> >
>>> > 3. Multi-document search is basically non-existent.
>>> >
>>> > 4. Automatic directories of all documents associated with a project is
>>> > not possible.
>>> >
>>> > 5. Google Takeout will not be able to distinguish which documents are
>>> > associated with the project, so if we ever have to migrate, we'll have
>>> > to do it one document at a time.
>>> >
>>> > On Wed, Jul 20, 2016 at 3:25 PM, Marcel Kornacker <marcel@cloudera.com>
>>> wrote:
>>> >> How about we scope that to everything that needs revisions/comments?
>>> >>
>>> >> On Wed, Jul 20, 2016 at 3:23 PM, Henry Robinson <henry@cloudera.com>
>>> wrote:
>>> >>> Seems reasonable, but I propose we scope that only to design documents
>>> >>> (which require revisions and comments).
>>> >>>
>>> >>> FWIW, Kudu includes building-from-source instructions on their website
>>> >>> (which I think is nicely done):
>>> >>> http://kudu.apache.org/docs/installation.html#_build_from_source
>>> >>>
>>> >>> I'm happy with most content going on the wiki.
>>> >>>
>>> >>> On 20 July 2016 at 09:44, Marcel Kornacker <marcel@cloudera.com>
>>> wrote:
>>> >>>
>>> >>>> A lot of our developer docs are Google docs, which facilitate
>>> >>>> commenting, and it would be good to keep it that way.
>>> >>>>
>>> >>>> Should we link to those docs from the Apache Impala wiki?
>>> >>>>
>>> >>>> On Wed, Jul 20, 2016 at 9:06 AM, Tim Armstrong <
>>> tarmstrong@cloudera.com>
>>> >>>> wrote:
>>> >>>> > I also think the wiki is the best approach.
>>> >>>> >
>>> >>>> > On Wed, Jul 20, 2016 at 8:55 AM, Jim Apple <jbapple@cloudera.com>
>>> wrote:
>>> >>>> >
>>> >>>> >> I think Tom's points are correct.
>>> >>>> >>
>>> >>>> >> Another option would be plain text or markdown files
inside the git
>>> >>>> >> repo. Those would be harder to update, but then would
have review
>>> for
>>> >>>> >> developer docs changes, which might be nice.
>>> >>>> >>
>>> >>>> >> FWIW, right now getting a wiki login requires asking
for one on
>>> this
>>> >>>> >> mailing list because of spambots.
>>> >>>> >>
>>> >>>> >> On Wed, Jul 20, 2016 at 1:37 AM, Tom White <tom@cloudera.com>
>>> wrote:
>>> >>>> >> > On Wed, Jul 20, 2016 at 4:56 AM, Dimitris Tsirogiannis
>>> >>>> >> > <dtsirogiannis@cloudera.com> wrote:
>>> >>>> >> >> Hi community,
>>> >>>> >> >>
>>> >>>> >> >> We need to move our developer documentation
to a proper
>>> location.
>>> >>>> >> >> Currently, it's in Cloudera's internal wiki
and in the wiki
>>> pages of
>>> >>>> the
>>> >>>> >> >> Cloudera Impala git repo (
>>> >>>> >> >> https://github.com/cloudera/Impala/wiki/Contributing-to-Impala
>>> ).
>>> >>>> >> >>
>>> >>>> >> >> The options are:
>>> >>>> >> >> * Impala's webpage (http://impala.io/)
>>> >>>> >> >
>>> >>>> >> > This is moving to http://impala.incubator.apache.org/,
so it's
>>> the
>>> >>>> >> > equivalent of the third option (below), isn't
it?
>>> >>>> >> >
>>> >>>> >> >> * Apache hosted Impala wiki (
>>> >>>> >> >> https://cwiki.apache.org/confluence/display/IMPALA/Impala+Home)
>>> >>>> >> >
>>> >>>> >> > This is probably the best since a wiki is the
most frictionless
>>> way of
>>> >>>> >> > updating dev docs.
>>> >>>> >> >
>>> >>>> >> >> * Apache hosted Impala webpage (
>>> http://impala.incubator.apache.org/)
>>> >>>> >> >> * The wiki pages of the Apache Impala git
repo (
>>> >>>> >> >> https://github.com/apache/incubator-impala)
>>> >>>> >> >
>>> >>>> >> > This isn't hosted on ASF infrastructure (unlike
source code
>>> which is
>>> >>>> >> > mirrored), so I think we can rule this one out.
>>> >>>> >> >
>>> >>>> >> > Thanks,
>>> >>>> >> > Tom
>>> >>>> >> >
>>> >>>> >> >>
>>> >>>> >> >> Please state your preference.
>>> >>>> >> >>
>>> >>>> >> >> Dimitris
>>> >>>> >>
>>> >>>>
>>> >>>
>>> >>>
>>> >>>
>>> >>> --
>>> >>> Henry Robinson
>>> >>> Software Engineer
>>> >>> Cloudera
>>> >>> 415-994-6679
>>>
>>
>>
>>
>> --
>> Henry Robinson
>> Software Engineer
>> Cloudera
>> 415-994-6679

Mime
View raw message