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
