+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 > > > > > > > > > >
