drill-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jacques Nadeau <jacq...@dremio.com>
Subject Re: [DISCUSS] - Design Docs
Date Wed, 07 Sep 2016 16:54:23 GMT
+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 <amansinha@apache.org> 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 <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
> > > >
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message