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 <jbap...@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 <mar...@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 <jbap...@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 <mar...@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 <he...@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 <mar...@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 < > tarmstr...@cloudera.com> > >>>>> wrote: > >>>>> > I also think the wiki is the best approach. > >>>>> > > >>>>> > On Wed, Jul 20, 2016 at 8:55 AM, Jim Apple <jbap...@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 <t...@cloudera.com> > wrote: > >>>>> >> > On Wed, Jul 20, 2016 at 4:56 AM, Dimitris Tsirogiannis > >>>>> >> > <dtsirogian...@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 >
