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