Mailing-List: contact dev-help@drill.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@drill.apache.org
MIME-Version: 1.0
In-Reply-To: <CALqceLHqvnUd9bN2JGTFp4nbZkZad0jcx7Kg3TOqiKLT7MBfNg@mail.gmail.com>
References: <CAAOiHjERdj56VaZynLcuL=gdvL88orUQ=4LkmKisfRu24U3gXw@mail.gmail.com>
 <CAEC1FanRo-Dmo8b_cAw2Ccf__DVMZ6jkWLWS0gvYNGbm0tGs6w@mail.gmail.com> <CALqceLHqvnUd9bN2JGTFp4nbZkZad0jcx7Kg3TOqiKLT7MBfNg@mail.gmail.com>
From: Aman Sinha <amansinha@apache.org>
Date: Tue, 6 Sep 2016 23:13:54 -0700
Message-ID: <CAFyDVvJSJBtWXXrvSPzKcL6-q3Z58hJDGj9cHMMK1DbJ9DfXgA@mail.gmail.com>
Subject: Re: [DISCUSS] - Design Docs
To: dev <dev@drill.apache.org>
Content-Type: multipart/alternative; boundary=001a1146acc65e2ca6053be4d1e5
archived-at: Wed, 07 Sep 2016 06:13:59 -0000

--001a1146acc65e2ca6053be4d1e5
Content-Type: text/plain; charset=UTF-8

+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 <kfaraaz@maprtech.com>
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 <gparai@maprtech.com> 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 <parthc@apache.org> 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
> > >
> >
>

--001a1146acc65e2ca6053be4d1e5--