+1 for the same repo. The closer docs can be to code the more accurate they
are likely to be. The same way we encourage unit tests for a new
feature/patch. Updating the docs can be the same.

If we follow Sqoop's process for example, how would small
fixes/adjustments/additions to the live documentation occur without a new
release?

On Thu, Aug 6, 2015 at 3:33 PM, Guozhang Wang <wangg...@gmail.com> wrote:

> I am +1 on same repo too. I think keeping one git history of code / doc
> change may actually be beneficial for this approach as well.
>
> Guozhang
>
> On Thu, Aug 6, 2015 at 9:16 AM, Gwen Shapira <g...@confluent.io> wrote:
>
> > I prefer same repo for one-commit / lower-barrier benefits.
> >
> > Sqoop has the following process, which decouples documentation changes
> from
> > website changes:
> >
> > 1. Code github repo contains a doc directory, with the documentation
> > written and maintained in AsciiDoc. Only one version of the
> documentation,
> > since it is source controlled with the code. (unlike current SVN where we
> > have directories per version)
> >
> > 2. Build process compiles the AsciiDoc to HTML and PDF
> >
> > 3. When releasing, we post the documentation of the new release to the
> > website
> >
> > Gwen
> >
> > On Thu, Aug 6, 2015 at 12:20 AM, Ismael Juma <ism...@juma.me.uk> wrote:
> >
> > > Hi,
> > >
> > > For reference, here is the previous discussion on moving the website to
> > > Git:
> > >
> > > http://search-hadoop.com/m/uyzND11JliU1E8QU92
> > >
> > > People were positive to the idea as Jay said. I would like to see a bit
> > of
> > > a discussion around whether the website should be part of the same repo
> > as
> > > the code or not. I'll get the ball rolling.
> > >
> > > Pros for same repo:
> > > * One commit can update the code and website, which means:
> > > ** Lower barrier for updating docs along with relevant code changes
> > > ** Easier to require that both are updated at the same time
> > > * More eyeballs on the website changes
> > > * Automatically branched with the relevant code
> > >
> > > Pros for separate repo:
> > > * Potentially simpler for website-only changes (smaller repo, less
> > > verification needed)
> > > * Website changes don't "clutter" the code Git history
> > > * No risk of website change affecting the code
> > >
> > > Your thoughts, please.
> > >
> > > Best,
> > > Ismael
> > >
> > > On Fri, Jul 31, 2015 at 6:15 PM, Aseem Bansal <asmbans...@gmail.com>
> > > wrote:
> > >
> > > > Hi
> > > >
> > > > When discussing on KAFKA-2364 migrating docs from svn to git came up.
> > > That
> > > > would make contributing to docs much easier. I have contributed to
> > > > groovy/grails via github so I think having mirror on github could be
> > > > useful.
> > > >
> > > > Also I think unless there is some good reason it should be a separate
> > > repo.
> > > > No need to mix docs and code.
> > > >
> > > > I can try that out.
> > > >
> > > > Thoughts?
> > > >
> > >
> >
>
>
>
> --
> -- Guozhang
>



-- 
Grant Henke
Software Engineer | Cloudera
gr...@cloudera.com | twitter.com/gchenke | linkedin.com/in/granthenke

Reply via email to