drill-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jinfeng Ni <...@apache.org>
Subject Re: [DISCUSS] - Design Docs
Date Wed, 07 Sep 2016 19:27:01 GMT
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 <pchandra@maprtech.com> 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 <jacques@dremio.com> 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 <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
View raw message