Hi, I'm in favor of moving away from HTML as well, while I have not had direct exposure to the pain points that Ewen mentions it is in general not pleasant to write docs in I think and bears a lot of risk of parsing failures etc.
I can't vote for using rst, not having used it, but I am happy to vote against markdown, as my own experience is that you hit its limitations fairly quickly and start looking for ways around these limitatios, which would likely make us end up in a similarly hacky place as where we are today, just on top of a different basis. Best regards, Sönke On Wed, Feb 7, 2018 at 2:55 AM, Guozhang Wang <wangg...@gmail.com> wrote: > Ewen, > > Thanks for re-picking this up again. I'm big +1 as I was two years ago :P > One thing that may still worth pointing out is that migrating from html > means that for any edits it would require one more compilation step to > review / compare the diffs if it is not only wording but also formatting / > displaying purposed. Personally I think it is worthy. > > As for rst v.s. markdown v.s. anything else, I'm also inclining to rst but > admittedly because I am familiar with rst than markdown as well. You have > listed quite a list of pros of rst on the ticket and I do not have more to > add. > > > Guozhang > > > On Tue, Feb 6, 2018 at 4:09 PM, Ewen Cheslack-Postava <e...@confluent.io> > wrote: > >> Hi all, >> >> I just wrote a note in https://issues.apache.org/jira/browse/KAFKA-2967 >> with a proposal for changing how docs are written. I want to move on this >> soon if possible and normally would just leave the discussion to the JIRA, >> but as I think this is something everyone has an opinion on and affects >> everyone contributing to the project, I figured I'd send this quick note to >> increase the likelihood people see it and have a chance to weigh in. >> >> Thanks, >> -Ewen >> > > > > -- > -- Guozhang -- Sönke Liebau Partner Tel. +49 179 7940878 OpenCore GmbH & Co. KG - Thomas-Mann-Straße 8 - 22880 Wedel - Germany
