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" <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 >>><[email protected]> >>> > 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 <[email protected]> >>>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 <[email protected]> >>> > 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> >>> > > >> ********************************************/ >>> > > >> >>> > > >>> > > >>> > >>>
