[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15183815#comment-15183815 ] Christian Posta edited comment on KAFKA-2967 at 3/7/16 10:05 PM: - All, I've got a quick spike of converting docs to gitbook https://www.gitbook.com which is basically markdown with some styling and can build websites, ebooks, pdf, etc. http://christianposta.com/kafka-docs/_book/index.html Point of this spike was to 1) get some feedback 2) understand how the current docs are folded into the website, and 3) figure out where some of the configs (e.g., broker configs) are in the website at apache, but not in the src :) For example, not all of these in the table here http://kafka.apache.org/documentation.html#brokerconfigs are in here https://github.com/apache/kafka/blob/trunk/docs/configuration.html#L147 This branch here as all of the code/integrated with gradle builds, etc https://github.com/christian-posta/kafka/tree/ceposta-doco again, this is currently WIP for discussion purposes, not complete by any means. was (Author: ceposta): All, I've got a quick spike of converting docs to gitbook https://www.gitbook.com which is basically markdown with some styling and can build websites, ebooks, pdf, etc. Point of this spike was to 1) get some feedback 2) understand how the current docs are folded into the website, and 3) figure out where some of the configs (e.g., broker configs) are in the website at apache, but not in the src :) For example, not all of these in the table here http://kafka.apache.org/documentation.html#brokerconfigs are in here https://github.com/apache/kafka/blob/trunk/docs/configuration.html#L147 This branch here as all of the code/integrated with gradle builds, etc https://github.com/christian-posta/kafka/tree/ceposta-doco again, this is currently WIP for discussion purposes, not complete by any means. > 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 > > 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)
[jira] [Comment Edited] (KAFKA-2967) Move Kafka documentation to ReStructuredText
[ https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15049105#comment-15049105 ] Jay Kreps edited comment on KAFKA-2967 at 12/9/15 6:14 PM: --- +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 using the framework to improve the thing the framework is used for. 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 big 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 understanding written 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 think improving the formatting engine could make things as much as 10% better but it could also make the resulting docs a lot worse if it changes how they're integrated into the site. 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 in styling, nav, etc. 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 indicative? Can we see what the proposed output would look like and how it would integrate before we adopt any change. That is the actually important thing. was (Author: jkreps): +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
