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 Wed, 20 Jul 2016 22:57:16 GMT
Oh, and, FWIW, I think Google docs are reasonable for design
proposals, because I expect those to be somewhat short-lived: once the
proposal is accepted, the design may very well stray from it based on
unforeseen implementation constraints, and we probably don't expect
contributors who do the implementation to go back and change the
design proposal as they work.

That seems very different to me than, for instance,
https://cwiki.apache.org/confluence/display/IMPALA/Tips+for+Faster+Impala+Builds
, which we do expect will be updated frequently and even by new
contributors and people who have just a minor update to make.

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

Mime
View raw message