I did a pass on the website. Changes: 1. Rewrote the 0.8 quickstart and included a section on running in distributed mode. 2. Fixed up the styles a bit. 3. Fixed the bizarre menu thing with 0.7 and 0.8 specific docs. 4. Re-wrote the copy on the front page.
I would love to get any feedback on how we could improve the site, documentation, etc.
I would like to do at least the following: 1. Generate scaladoc just for the client classes. 2. See if there isn't some way to generate javadoc for the java api 3. Rewrite the design document for 0.8 4. Update the operations guide to cover 0.8
Looks good overall - thanks a lot for the improvements.
Couple of comments: clicking on the 0.7 link goes to the migration page (which should probably be on the 0.8 link) Also, for the configuration.html file, I used to find the old scala docs pointing to the actual *Config classes more current and informative. The site can drift over time.
On Fri, Jun 28, 2013 at 2:49 PM, Sriram Subramanian <[EMAIL PROTECTED]> wrote:
Ack, nice catch--that migration tool thing was due to bad html, I forgot to close the link.
For the configuration I actually think that is not right. We need to thoroughly document our configuration. Having the code/scaladoc be the documentation is fine for kafka developers but not where we want to be.
In the future I would love us to move to a method of defining configs that was something like: configs.define(name = "port", type="int", max=Int.MaxValue, min=0, required=true, documentation="The port used by the kafka broker to handle requests.") If we did it this way we could actually have a dumpConfigs method that would print out the up-to-date table of configs so we could more easily keep the docs in sync.
For the time being, though, we should just keep the docs updated.
On Fri, Jun 28, 2013 at 5:55 PM, Joel Koshy <[EMAIL PROTECTED]> wrote:
Yeah thanks for the feedback, that's helpful. Here was my thinking: 1. I think it just makes sense to have one design and implementation page which describe the most recent release and live at the top level. You could imagine wanting to read older design pages but that seems a bit unlikely mostly, and it will be really duplicative since the design generally won't change a ton, so I think it is just confusing. Currently the design and implementation page only cover 0.7 but that's just because I haven't gotten there yet--I hope to get to them in the next week. 2. Oops that's a typo will fix. I wanted to kind of walk people through things step by step. I like to do tutorials like that where you just kind of cut and paste commands and watch what happens, that was the rationale for repeating the command. 3. I guess I felt that although we do document that tool, migration is important and a person interested in 0.8 would be more likely to look under "migration" than tools. I like the idea of having a tools page but right now it is very incomplete as it doesn't cover most of the tools. Anyhow I thought migration was important enough to get its own link. 4. I agree. The old link structure was insane though as all the menus disappeared when you clicked on a link and we had cut and pasted all the shared files into the release dirs. Here was my plan. For now I think 0.7 is the only stable release and 0.8 is beta so it makes sense to have them both though that does take up a lot of space. When we think 0.7 is no longer relevant I will make an expandable nav with the title "older releases" and shove that in there so when you click "older releases" it will unhide all the old releases (which at first will just be 0.7). That way we don't keep taking up space.
I was going to put another day of work into the docs. My plan was to add a "use cases" page that covers the basics of tracking, messaging, etc, and update the design page. If anyone else has ideas for other improvements let me know?
Question: do you have any feedback on the intro page? The goal of that was to be something someone who just wants the basics of what Kafka is to read. It is a bit hard to write something like this because you have to put yourself in the shoes of someone totally new to Kafka and potentially new to messaging and log aggregation and still explain things coherently. Previously the only explanatory thing we had was the design page which was extremely detailed so pulling out the essentials hopefully gives a kind of executive summary.
On Sun, Jun 30, 2013 at 3:32 PM, Jun Rao <[EMAIL PROTECTED]> wrote:
-Jay On Wed, Jul 3, 2013 at 5:42 AM, Markus Roder <[EMAIL PROTECTED]>wrote:
NEW: Monitor These Apps!
Apache Lucene, Apache Solr and all other Apache Software Foundation projects and their respective logos are trademarks of the Apache Software Foundation.
Elasticsearch, Kibana, Logstash, and Beats are trademarks of Elasticsearch BV, registered in the U.S. and in other countries. This site and Sematext Group is in no way affiliated with Elasticsearch BV.
Service operated by Sematext