> > 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...).
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+Protocol > > > ZK layout: > > > > > > > https://cwiki.apache.org/confluence/display/KAFKA/Kafka+data+structures+in+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
