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 >>>>> >>>>> >>> >>> > >
