Yes it is easier to comment in a Google doc, but the comments are not automagically posted on the dev list or the JIRA. That way a search of the archives does not pick up the comments. On the other hand, if we have a Gist or MD file in github, others can comment on it. [1] is an example of what others are doing.
At the moment, though, I just want to make the template available to folks so that it can be used as a basis for writing design proposals. It makes it easier for inexperienced writers and enumerates the considerations that we should put into design docs. For myself, I plan to put any docs I write into Google docs as well as Gist. If we come up with a better tool, I'll switch to that. [1] https://github.com/golang/proposal On Wed, Sep 7, 2016 at 12:27 PM, Jinfeng Ni <[email protected]> wrote: > When the design doc is in early stage, and soliciting for people's > comment, I like Google doc since it makes easier for people to put > their comments and the comments are directly associated with the > original doc. I'm not sure how easy it is to put comments in Gist or > markdown doc, and how to connect the comments with the original doc. > > I thought as long as the Apache JIRA has a link to the google doc and > it is accessible to everyone, then everyone can find the doc and > comments from the link in the JIRA. > > On Wed, Sep 7, 2016 at 10:46 AM, Parth Chandra <[email protected]> > wrote: > > For Drill-4800 I used both Gist and Google docs but comments came in thru > > JIRA. The Gist doc was in my github so not hooked up into JIRA, but I > think > > that could be made to work. > > (I like Gist even though it is sort of painful to format the doc and to > add > > images.) > > > > On Wed, Sep 7, 2016 at 9:54 AM, Jacques Nadeau <[email protected]> > wrote: > > > >> +1 for better design docs > >> -1 for using something disconnected from the mailing list > >> > >> I think we need to have a way that the design doc is more connected to > >> mailing lists. Design docs in Google docs are problematic because a > bunch > >> of discussion happens independent of the list which is contrary to the > >> apache way. (Remember the old mantra, if it didn't happen on the list, > it > >> didn't happen). If a developer happens to miss the post which is "here > is a > >> new design doc", developers will never realize a conversation is > happening > >> and important design decisions are occurring. I think this constantly > been > >> a problem when we've tried using google docs in the past. I'm up for > other > >> ideas. Some: google docs where all comments and edits come back to dev > list > >> (possible/how?), use jira for design docs, markdown design docs in > separate > >> Drill branch using github comments to shape, or a better idea? > >> > >> -- > >> Jacques Nadeau > >> CTO and Co-Founder, Dremio > >> > >> On Tue, Sep 6, 2016 at 11:13 PM, Aman Sinha <[email protected]> > wrote: > >> > >> > +1 on using a design doc template for features that are of moderate or > >> > higher complexity. Many of the sections are optional, so it should > >> > hopefully be considered 'lightweight' enough to encourage more people > to > >> > adopt it. > >> > > >> > On Tue, Sep 6, 2016 at 10:22 PM, Khurram Faraaz <[email protected] > > > >> > wrote: > >> > > >> > > Should we have the Document history table at the beginning of the > >> > document, > >> > > that way reviewers and readers of the design document will know if > the > >> > > document has already gone through a few review cycles ? > >> > > > >> > > On Wed, Sep 7, 2016 at 7:28 AM, Gautam Parai <[email protected]> > >> > wrote: > >> > > > >> > > > Thanks so much for writing design documents for complex projects! > >> They > >> > > are > >> > > > very helpful in learning about Drill Internals especially for new > >> > > > contributors like me - most recently Drill 4280. > >> > > > > >> > > > The design document template [2] looks good to me. > >> > > > > >> > > > For the reviews, I like Google Docs since it makes the document > easy > >> to > >> > > > share and review :) > >> > > > > >> > > > Gautam > >> > > > > >> > > > > >> > > > On Tue, Sep 6, 2016 at 5:49 PM, Parth Chandra <[email protected]> > >> > wrote: > >> > > > > >> > > > > We had a discussion on the dev list nearly a year ago about > getting > >> > > > better > >> > > > > at documenting designs in Drill [1]. We were all mostly in > >> agreement > >> > > > that > >> > > > > we should write better design documents and I just wanted to > >> revisit > >> > > the > >> > > > > topic. > >> > > > > > >> > > > > Some of the more complex features being worked on recently, > >> > DRILL-4800 > >> > > > and > >> > > > > DRILL-4820 to name a couple, have used a common format for the > >> > design, > >> > > > and > >> > > > > it has proven to be quite useful. > >> > > > > > >> > > > > I've put a basic template at [2]. Do folks have any comments > about > >> > the > >> > > > > template? I would like to encourage folks working on complex > >> features > >> > > to > >> > > > > use this as a guideline to writing design proposals and for > >> reviewers > >> > > to > >> > > > > use while reviewing. I don't think every JIRA needs a design > >> document > >> > > > > (sometimes the JIRA is enough), and I would leave it open for > the > >> > > > > contributor to use whatever technology they feel comfortable > with > >> > > > (provided > >> > > > > reviewers can comment easily). > >> > > > > > >> > > > > What do people think? If everyone agrees I would like to > provide a > >> > link > >> > > > to > >> > > > > this document from the Contribute to Drill page. > >> > > > > > >> > > > > > >> > > > > Parth > >> > > > > > >> > > > > > >> > > > > [1] > >> > > > > http://mail-archives.apache.org/mod_mbox/drill-dev/201510. > >> > > > > mbox/%3CCAAOiHjFDOZE%2Br2zmn%2BYWF% > 3DbKc4JAocVKGcvaCpfTj0gXdfxLUw > >> > > > > %40mail.gmail.com%3E > >> > > > > [2] > >> > > > > https://docs.google.com/document/d/1PnBiOMV5mYBi5N6fLci- > >> > > > > bRTva1gieCuxwlSYH9crMhU/edit?usp=sharing > >> > > > > > >> > > > > >> > > > >> > > >> >
