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