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