+1
On Thu, Oct 23, 2014 at 11:45 AM, Sriram Subramanian <srsubraman...@linkedin.com.invalid> wrote: > I actually think it is a pretty good idea to have the docs in git. > Summarizing the benefits - > > 1. If a contributor/committer makes any significant changes to how a > functionality works, they could always update the docs in parallel and > reviewers can enforce this if they find the change deems a documentation > change. The will help us to create a process around updating documentation > which is hard today. > 2. Creating a new version can be done when we cut a new branch. This seems > a lot easier than remembering to update the documentation for a new > version as an after thought. > 3. Easy to review the docs with the code change in mind. We forget the > exact changes over time and reviewers would need to review the code again > to do a good review of the docs. > > +1 from me. > > On 10/23/14 10:37 AM, "Gwen Shapira" <gshap...@cloudera.com> wrote: > >>With two patches, we'll need a two-phase commit to maintain >>consistency, and we all know what a PITA this can be. >>(Sorry, couldn't resist the pun. Carry on.) >> >>On Thu, Oct 23, 2014 at 10:32 AM, Jay Kreps <jay.kr...@gmail.com> wrote: >>> That makes sense. I agree that moving to another doc system isn't a high >>> priority (it isn't as much work as it sounds because the HTML can all >>> remain as is, just the includes would get converted). But actually I >>>don't >>> think that having a patch for docs and a patch for the code is too big a >>> hurdle either. I think maybe we should just start asking for >>>documentation >>> patches and describe that in the contributing section--likely most >>>people >>> just don't think of it. >>> >>> -Jay >>> >>> On Thu, Oct 23, 2014 at 7:16 AM, Joe Stein <joe.st...@stealth.ly> wrote: >>> >>>> I like how we have things in SVN. My issue is having two patches from >>>> contributors (one for tests + code and another for docs) that I am >>>>trying >>>> to solve. >>>> >>>> If we copy the entire SVN docs directory into git under /docs then >>>> contributions can patch the docs in their git patch. Committers can do >>>>1 >>>> commit. >>>> >>>> When we release we just cp -r docs/* /svn/ && svn add * && svn co >>>> "release" //or such. The only trick is that we have to make sure for >>>>live >>>> website fixes that we commit in two places (but only then instead of >>>>every >>>> time). I don't mind doing something more fancy and generate the docs >>>>from >>>> some markdown but I am not sure it is necessary... we have a lot to get >>>> done in the next few months with 0.9 and I don't want to add anything >>>> unnecessary to that effort. >>>> >>>> I do think though with all the changes coming we want code >>>>contributors to >>>> keep the docs up to date and have doc changes + code + test all in one >>>>git >>>> patch would be best for everyone (however we accomplish that) for >>>>reviewing >>>> and such. >>>> >>>> /******************************************* >>>> Joe Stein >>>> Founder, Principal Consultant >>>> Big Data Open Source Security LLC >>>> http://www.stealth.ly >>>> Twitter: @allthingshadoop <http://www.twitter.com/allthingshadoop> >>>> ********************************************/ >>>> >>>> On Wed, Oct 22, 2014 at 1:53 PM, Jay Kreps <jay.kr...@gmail.com> wrote: >>>> >>>> > Currently we are handling the versioning problem by explicitly >>>>versioning >>>> > docs that change over time (configuration, quickstart, design, etc). >>>>This >>>> > is done by just creating a copy of these pages for each release in a >>>> > subdirectory. So we can commit documentation changes at any time for >>>>the >>>> > future release we just don't link up that release until it is out >>>> > (theoretically you could get there by guessing the url, but that is >>>> okay). >>>> > Although having multiple copies of certain pages, one for each >>>>release, >>>> > seems odd, I think it is actually better because in practice we >>>>often end >>>> > up editing old releases when we find problems in the older docs. >>>> > >>>> > -Jay >>>> > >>>> > On Wed, Oct 22, 2014 at 10:35 AM, Jarek Jarcec Cecho >>>><jar...@apache.org> >>>> > wrote: >>>> > >>>> > > I would strongly support this idea. We have similar model in all >>>>other >>>> > > projects where I¹m involved: >>>> > > >>>> > > The docs are part of the usual code base and we do require >>>>contributors >>>> > to >>>> > > update them when they are adding a new feature. And then during >>>>release >>>> > > time we simply take snapshot of the docs and upload them to our >>>>public >>>> > > webpages. This enables us to have simple versioned docs on the >>>>website, >>>> > so >>>> > > that users can easily find docs for their version and also the >>>>public >>>> > site >>>> > > do not contain docs of unreleased features :) There is a lot of >>>>ways >>>> how >>>> > to >>>> > > achieve that - in Sqoop 1 we used asciidoc to build the site, in >>>>Sqoop >>>> > > 2/Flume we¹re using sphinx, Oozie is using markdown wiki... >>>> > > >>>> > > Jarcec >>>> > > >>>> > > > On Oct 22, 2014, at 10:27 AM, Jay Kreps <jay.kr...@gmail.com> >>>>wrote: >>>> > > > >>>> > > > Hey Joe, >>>> > > > >>>> > > > I'd love to encourage documentation contributions. >>>> > > > >>>> > > > I think we do have a way to contribute to docs. The current >>>>workflow >>>> > for >>>> > > > contributing is >>>> > > > 1. Checkout the docs >>>> > > > 2. Change docs >>>> > > > 3. Submit patch in normal way >>>> > > > 4. Committer reviews and applies >>>> > > > >>>> > > > For committers we have traditionally made the review step >>>>optional >>>> for >>>> > > docs. >>>> > > > >>>> > > > In reality this skips step 1.5 which is fiddling with apache for >>>>an >>>> > hour >>>> > > to >>>> > > > figure out how to get it to make apache includes work so you can >>>>see >>>> > the >>>> > > > docs. I actually think this is the bigger barrier to doc changes. >>>> > > > >>>> > > > One thing we could do is move the docs to one of the static site >>>> > > generators >>>> > > > to do the includes (e.g. Jekyll) this might make setup slightly >>>> easier >>>> > > > (although then you need to install Jekyll...). >>>> > > > >>>> > > > -Jay >>>> > > > >>>> > > > On Wed, Oct 22, 2014 at 9:55 AM, Joe Stein <joe.st...@stealth.ly> >>>> > wrote: >>>> > > > >>>> > > >> This comes up a lot but in reality not enough. We don't have a >>>> great >>>> > > way >>>> > > >> for folks to modify the code and change (or add) to the >>>> > documentation. I >>>> > > >> think the documentation is awesome and as we grow the code >>>> > contributors >>>> > > >> that should continue with them too. >>>> > > >> >>>> > > >> One thought I had that would work is that we copy the SVN files >>>> into a >>>> > > >> /docs folder in git. We can then take patches in git and then >>>>apply >>>> > > them >>>> > > >> to SVN when appropriate (like during a release or for immediate >>>> > fixes). >>>> > > >> This way code changes in that patch can have documentation >>>>changes. >>>> > The >>>> > > >> committers can manage what is changed where as appropriate >>>>either >>>> > prior >>>> > > to >>>> > > >> a release or live updates to the website. Yes/No? >>>> > > >> >>>> > > >> Thanks! >>>> > > >> >>>> > > >> /******************************************* >>>> > > >> Joe Stein >>>> > > >> Founder, Principal Consultant >>>> > > >> Big Data Open Source Security LLC >>>> > > >> http://www.stealth.ly >>>> > > >> Twitter: @allthingshadoop >>>><http://www.twitter.com/allthingshadoop> >>>> > > >> ********************************************/ >>>> > > >> >>>> > > >>>> > > >>>> > >>>> >
