kafka-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jakob Homan <jgho...@gmail.com>
Subject Re: Kafka questions
Date Wed, 20 Jul 2011 18:17:40 GMT
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.

On Wed, Jul 20, 2011 at 10:41 AM, Alan D. Cabrera <list@toolazydogs.com> 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 <list@toolazydogs.com> 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 <list@toolazydogs.com>
>>>>> 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
>>>>>> recorded for posterity. The only barrier to entry to the discussion
>>>>>> 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

View raw message