Ewen Cheslack-Postava commented on KAFKA-2967:

Hey folks, I just want to point out that it isn't really useful to just upvote 
a particular format without more details. The point of restarting the 
discussion here was to be able to make progress on this with:
 # A practical choice of documentation system (guess I was correct that it 
would inevitably be a bikeshedding discussion)
 # A practical plan for a how this will work, including addressing concerns 
like Jay's about making it a clean integration with the rest of the website 
which likely would not make sense to translate into the docs system. 
 # People who are a) ready to spend time on this and b) familiar enough with a 
particular tool that we have a reasonable plan

It seems like everyone is only addressing 1. For all the asciidoc voters, can 
you outline details for 2 & 3? For RST/sphinx we already have a PR prepared 
(and in very short order, I might add) that is like 95% there. I need to find a 
bit of time to look into integrating it with the gradle build, but since we 
already knew rst inside out, we were able to do this very quickly. I have never 
used asciidoc and we won't have the time or resources to spend converting to 
that – can someone else contribute the resources for that? If not, are we 
actually concerned about it being in rst rather than asciidoc or are these just 
preferences, i.e. in what ways would asciidoc be such a huge win over rst?

Note that a major reason we're still writing all our docs in html over 2 years 
later is bikeshedding on the particular format.

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

Reply via email to