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 document.)
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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >> 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 <[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 >>>>>>>> >>>>>>> >>>>>> >>>>> >>>> >>
