[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17243870#comment-17243870
]
Tom Bentley commented on KAFKA-2967:
------------------------------------
To summarize this thread, Ewen originally proposed ReStructured Text and while
everyone agreed that it was no fun editing HTML, a significant number of people
would have preferred Asciidoc. While I can get behind a move to use markdown
(because practically anything is better than HTML), I'm not convinced that it's
better than either Asciidoc or RST.
As one example, I opened https://github.com/apache/kafka/pull/9658 last week
and while something like that could probably be made to work for Asciidoc or
RST I don't think it would really work in markdown. That's just one example of
how the constrained syntax of markdown could actually work _against_ longer
term improvements to documentation which would benefit readers.
So while I applaud [~JimGalasyn] for taking this on, are we really sure that
we're choosing markdown for good reasons?
> Move Kafka documentation to ReStructuredText
> --------------------------------------------
>
> Key: KAFKA-2967
> URL: https://issues.apache.org/jira/browse/KAFKA-2967
> Project: Kafka
> Issue Type: Bug
> Reporter: Gwen Shapira
> Assignee: Gwen Shapira
> Priority: Major
> Labels: documentation
>
> Storing documentation as HTML is kind of BS :)
> * Formatting is a pain, and making it look good is even worse
> * Its just HTML, can't generate PDFs
> * Reading and editting is painful
> * Validating changes is hard because our formatting relies on all kinds of
> Apache Server features.
> I suggest:
> * Move to RST
> * Generate HTML and PDF during build using Sphinx plugin for Gradle.
> Lots of Apache projects are doing this.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
