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> > > >> ********************************************/ > > >> > > > > >
