On Thu, Mar 26, 2015 at 9:46 PM, Jay Kreps <jay.kr...@gmail.com> wrote: > The reason the docs are in svn is that when we were setting up the site > apache required that to publish doc changes. Two possible fixes: > 1. Follow up with infra to see if they have git integration working yet > 2. Move to a model where doc "source" is kept in the main git and we use > jenkyl or something like that to generate result html (i.e. with things > like headers) and then check that in to svn to publish it. > > The second item would have the advantage of not needing to configure apache > includes to see the docs, but would likely trade it for jenkyl setup stuff. > Jenkyl might actually fix a lot of the repetitive stuff in the docs today > (e.g. generating section numbers, adding <p> tags, etc).
What we do at other projects that I'm familiar with (Sqoop, Flume) is that we manage the docs "source" (i.e. asciidoc or similar) in git. When its time to release a version (i.e. after a successful vote on RC), we build the docs, manually copy to the SVN repo and push (or whatever the SVN equivalent...). Its a bit of a manual pain, but its only few times a year. This is also a good opportunity to upload updated javadocs, docs generated from ConfigDef and KafkaMetrics, etc. Gwen > > -Jay > > On Thu, Mar 26, 2015 at 8:22 PM, Jiangjie Qin <j...@linkedin.com.invalid> > wrote: > >> >> >> On 3/26/15, 7:00 PM, "Neha Narkhede" <n...@confluent.io> wrote: >> >> >> >> >> Much much easier to do this if the docs are in git and can be reviewed >> >>and >> >> committed / reverted with the code (transactions makes synchronization >> >> easier...). >> +1 on this, too! >> > >> > >> >Huge +1. >> > >> >On Thu, Mar 26, 2015 at 6:54 PM, Joel Koshy <jjkosh...@gmail.com> wrote: >> > >> >> +1 >> >> >> >> It is indeed too easy to forget and realize only much later that a >> >> jira needed a doc update. So getting into the habit of asking "did you >> >> update the docs" as part of review will definitely help. >> >> >> >> On Thu, Mar 26, 2015 at 06:36:43PM -0700, Gwen Shapira wrote: >> >> > I strongly support the goal of keeping docs and code in sync. >> >> > >> >> > Much much easier to do this if the docs are in git and can be reviewed >> >> and >> >> > committed / reverted with the code (transactions makes synchronization >> >> > easier...). >> >> > >> >> > This will also allow us to: >> >> > 1. Include the docs in the bits we release >> >> > 2. On release, update the website with the docs from the specific >> >>branch >> >> > that was just released >> >> > 3. Hook our build to ReadTheDocs and update the "trunk" docs with >> >>every >> >> > commit >> >> > >> >> > >> >> > Tons of Apache projects do this already and having reviews enforce the >> >> "did >> >> > you update the docs" before committing is the best way to guarantee >> >> updated >> >> > docs. >> >> > >> >> > Gwen >> >> > >> >> > On Thu, Mar 26, 2015 at 6:27 PM, Jun Rao <j...@confluent.io> wrote: >> >> > >> >> > > Hi, Everyone, >> >> > > >> >> > > Quite a few jiras these days require documentation changes (e.g., >> >>wire >> >> > > protocol, ZK layout, configs, jmx, etc). Historically, we have been >> >> > > updating the documentation just before we do a release. The issue is >> >> that >> >> > > some of the changes will be missed since they were done a while >> >>back. >> >> > > Another way to do that is to keep the docs updated as we complete >> >>each >> >> > > jira. Currently, our documentations are in the following places. >> >> > > >> >> > > wire protocol: >> >> > > >> >> > > >> >> >> >> >> https://cwiki.apache.org/confluence/display/KAFKA/A+Guide+To+The+Kafka+Pr >> >>otocol >> >> > > ZK layout: >> >> > > >> >> > > >> >> >> >> >> https://cwiki.apache.org/confluence/display/KAFKA/Kafka+data+structures+i >> >>n+Zookeeper >> >> > > configs/jmx: https://svn.apache.org/repos/asf/kafka/site/083 >> >> > > >> >> > > We probably don't need to update configs already ported to ConfigDef >> >> since >> >> > > they can be generated automatically. However, for the rest of the >> >>doc >> >> > > related changes, keeping they updated per jira seems a better >> >>approach. >> >> > > What do people think? >> >> > > >> >> > > Thanks, >> >> > > >> >> > > Jun >> >> > > >> >> >> >> >> > >> > >> >-- >> >Thanks, >> >Neha >> >>
