+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 > >
