impala-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dimitris Tsirogiannis <dtsirogian...@cloudera.com>
Subject Re: Location of developers documentation
Date Thu, 21 Jul 2016 03:05:58 GMT
By developer documentation I meant anything that is currently under the
"For Developers" section in the wiki (
https://github.com/cloudera/Impala/wiki).

Dimitris

On Wed, Jul 20, 2016 at 4:40 PM, Jim Apple <jbapple@cloudera.com> wrote:

> I think it is reasonable for contributors to use Google Docs for
> coordinating short-lived, heavily commented documents.
>
> However, I don't think Dimitris was referring to those sort of things.
>
> On Wed, Jul 20, 2016 at 4:18 PM, 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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message