drill-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Rogers <prog...@maprtech.com>
Subject Re: [DISCUSS] - Design Docs
Date Thu, 08 Sep 2016 16:24:52 GMT
I like the template. The key contribution of the template is to remind us of the topics and
suggest a default document structure with which to start. It will turn out that each project
will need to make adjustments (topic A expands into multiple sections, say, topics B and C
are trivial and collapse into a single section, and topic D is already covered in an existing

As it turns out, we already use separate forums for specialized discussions: pull requests.
In a similar fashion, perhaps it is reasonable to use Google docs (or whatever) for detailed
design decisions. Bring to this list notifications of new documents, major revisions, and
key design questions: (“we planned to do extend A, but we’ve now decide to replace A with
a new B.”) so that people are prompted to jump into the detailed discussion when an interesting
topic arises.

As for tool; the Confluence Wiki is great: all the material is in one place; it tracks comments
and changes, you can be notified of each revision. Apache licenses Confluence JIRA. Can we
also get a Confluence Wiki license?

- Paul

> On Sep 7, 2016, at 1:50 PM, Parth Chandra <parthc@apache.org> wrote:
> Yes it is easier to comment in a Google doc, but the comments are not
> automagically posted on the dev list or the JIRA. That way a search of the
> archives does not pick up the comments.
> On the other hand, if we have a Gist or MD file in github, others can
> comment on it.
> [1] is an example of what others are doing.
> At the moment, though, I just want to make the template available to folks
> so that it can be used as a basis for writing design proposals. It makes it
> easier for inexperienced writers and enumerates the considerations that we
> should put into design docs.
> For myself, I plan to put any docs I write into Google docs as well as
> Gist. If we come up with a better tool, I'll switch to that.
> [1] https://github.com/golang/proposal
> On Wed, Sep 7, 2016 at 12:27 PM, Jinfeng Ni <jni@apache.org> wrote:
>> 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
>>>>>>> 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
>>>> agreement
>>>>>>> that
>>>>>>>> we should write better design documents and I just wanted
>>>> 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
>>>>> 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
>> 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

View raw message