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