[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15049105#comment-15049105
]
Jay Kreps commented on KAFKA-2967:
----------------------------------
+0
We've been through a few rounds of this and doc changes tend to be a bit like
build system changes. Lots of people get excited about changing the framework,
no one gets excited about the thing the framework is used for better. We
usually end up moving over to something no one understands and then it is
poorly maintained (we are on build system iteration 5 by my count).
I'm in favor of removing the dependency on apache SSI, I think that would be a
bit improvement.
An easier approach might be to use something like Jykell that would allow us to
take what we have as is, and move to markdown bit-by-bit as a convenience; it
also allows you to fall back to html wherever needed and makes live preview
fairly easy to set up.
I feel previous attempts in this area have optimized for the wrong things. In
general we write the docs once, the hard part tends to be the good english
explanations written by people with deep understand for people with no
understanding.
The big problem with the existing docs is that many areas are poorly covered or
confusing or out of date. Personally, I think this is secondary to the
formatting engine.
I agree HTML formatting is verbose, but:
- Everyone in the world knows it.
- If you don't it is easy to google
- It is incredibly flexible
Various things that translate to HTML fix the verbosity but often are very
limited in what they can do and require you to learn a whole tool chain and
markup language.
A few things I think that are really important:
- The docs should stay part of the main site. Doc things like sphynx that dump
you into a whole different site with different nav and theming is just a
terrible experience.
- The output should look no worse than it currently does. That restructured
text page looks like it was imported from 1997. Hopefully that is not
indicitive?
Can we see what the proposed output would look like before we adopt any change.
That is the actually important thing.
> 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
>
> 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
(v6.3.4#6332)
