Good examples. Thanks for pointing them out. Now that I see that PDFs are not a barrier to open discussions, it's up to you guys.
Thanks again! Regards, Alan On Jul 20, 2011, at 11:17 AM, Jakob Homan wrote: > I'm not meaning to push back; just curious as to the drawbacks of PDFs > versus wikis. I was surprised to see PDF-backed design docs described > as "very bad" when I've seen this approach work well in multiple > projects (e.g. HDFS-265, MAPREDUCE-326, HBASE-3857, ZOOKEEPER-1016, > BOOKKEEPER-11, HDFS-1073, HIVE-1555). Posting PDFs and the > change-driver incorporating feedback until consensus emerges seems > like a more natural counterpart to our SOP of posting patches and the > coder incorporating feedback until +1 is given. > -jg > > > On Wed, Jul 20, 2011 at 10:41 AM, Alan D. Cabrera <[email protected]> > wrote: >> Yeah, that's the point of a wiki, sharing. One person should not own a >> design doc. Frankly, I don't understand the push back for such a simple >> document. >> >> >> Regards, >> Alan >> >> >> On Jul 20, 2011, at 10:34 AM, Jakob Homan wrote: >> >>> Doesn't need to be, but could be. It's usually up to the person >>> proposing the change/driving the discussion to create new versions of >>> the PDF. In my experience, when people attached the Word doc, others >>> would complain that they didn't have Word, and when people attached, >>> e.g., the laTex document people would have complain they didn't know >>> ancient Egyptian... >>> -jg >>> >>> On Wed, Jul 20, 2011 at 10:19 AM, Alan D. Cabrera <[email protected]> >>> wrote: >>>> Are you saying that the source document for the PDF is also attached to >>>> the issue? I don't see it in KAFKA-50. >>>> >>>> >>>> Regards, >>>> Alan >>>> >>>> On Jul 20, 2011, at 10:11 AM, Jakob Homan wrote: >>>> >>>>> I don't have anything against wikis - they're great for information >>>>> that changes more frequently than releases are made and should be >>>>> user-facing (configuration, FAQs, etc). >>>>> >>>>> For large technical changes, like the one currently being propsosed, >>>>> the PDF isn't static, but will have several versions posted. The >>>>> whole discussion is: PDF version 0, then comments on that PDF, then >>>>> PDFv1, then more discussions until eventually the discussion turns >>>>> into +1s and the final version of the PDF is attached. The JIRA does >>>>> a good job of chronicling the discussion that wiki change logs >>>>> doesn't. JIRA just seems like a more natural forum to spur >>>>> discussion. >>>>> >>>>> Also, having the person driving the change updating the document tends >>>>> to keep the discussion on track and making progress. >>>>> >>>>> Finally, new or less senior members of the community may be reluctant >>>>> to edit a semi-official project document like a wiki, but hopefully >>>>> will be willing to join in the discussion on JIRA. >>>>> -jg >>>>> >>>>> >>>>> On Wed, Jul 20, 2011 at 9:56 AM, Alan D. Cabrera <[email protected]> >>>>> wrote: >>>>>> >>>>>> On Jul 20, 2011, at 9:51 AM, Jakob Homan wrote: >>>>>> >>>>>>>>> and then just comment and iterate over there. Is that not the >>>>>>>>> preferred way? >>>>>>>> >>>>>>>> No, that's very bad. There's no way that others can participate and >>>>>>>> modify the design. >>>>>>>> >>>>>>> >>>>>>> How so? The documentation is online and the discussion is online and >>>>>>> recorded for posterity. The only barrier to entry to the discussion is >>>>>>> setting up a JIRA account. >>>>>> >>>>>> The design document should be open to the community to edit. Not a >>>>>> frozen PDF document. I'll turn the question around. What problem do >>>>>> you see storing the document in a wiki format? >>>>>> >>>>>> >>>>>> Regards, >>>>>> Alan >>>>>> >>>>>> >>>> >>>> >> >>
