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 >
