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). -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 > >
