kafka-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sönke Liebau <soenke.lie...@opencore.com.INVALID>
Subject Re: Documentation build system
Date Wed, 07 Feb 2018 12:33:51 GMT

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,

On Wed, Feb 7, 2018 at 2:55 AM, Guozhang Wang <wangguoz@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 <ewen@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
Tel. +49 179 7940878
OpenCore GmbH & Co. KG - Thomas-Mann-Straße 8 - 22880 Wedel - Germany

View raw message