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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >> wrote: >>> How about we scope that to everything that needs revisions/comments? >>> >>> On Wed, Jul 20, 2016 at 3:23 PM, Henry Robinson <[email protected]> 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 <[email protected]> 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 <[email protected]> >>>>> wrote: >>>>> > I also think the wiki is the best approach. >>>>> > >>>>> > On Wed, Jul 20, 2016 at 8:55 AM, Jim Apple <[email protected]> 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 <[email protected]> wrote: >>>>> >> > On Wed, Jul 20, 2016 at 4:56 AM, Dimitris Tsirogiannis >>>>> >> > <[email protected]> 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
