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