Re: Creating an Apache cloudstack docs repo: please discuss

[Joe Brockmeier <jz...@zonker.net>]

On Sat, Jun 30, 2012 at 04:27:30PM +0200, Mohammad Nour El-Din wrote:
> I would go with approch of having the docs in the same repo under say /docs
> as David mentioned

+1 

Some projects may do this differently, but it's usually the norm to keep
documentation with the rest of the code. 

> Take into account that having more than one repo will need more work and
> infra management

Not to mention a headache for anyone working with CloudStack code and
docs.

Best, 

Joe
-- 
"Another flaw in the human character is that everybody wants 
to build and nobody wants to do maintenance." ~ Kurt Vonnegut

Joe 'Zonker' Brockmeier <jz...@zonker.net>

RE: Creating an Apache cloudstack docs repo: please discuss

[Deepak Garg <de...@citrix.com>]

The dev documentation may be kept in the same repo which will talk about the APIs, architecture etc. but documentation like 'install guide', 'quick install guide', 'setting up xyz environment' where xyz could be Nicira switch or some other external piece, should be kept in a separate repo IMO.



Deepak


-----Original Message-----
From: Joe Brockmeier [mailto:jzb@zonker.net] 
Sent: Monday, July 02, 2012 8:53 AM
To: cloudstack-dev@incubator.apache.org
Subject: Re: Creating an Apache cloudstack docs repo: please discuss

On Sat, Jun 30, 2012 at 04:27:30PM +0200, Mohammad Nour El-Din wrote:
> I would go with approch of having the docs in the same repo under say /docs
> as David mentioned

+1 

Some projects may do this differently, but it's usually the norm to keep
documentation with the rest of the code. 

> Take into account that having more than one repo will need more work and
> infra management

Not to mention a headache for anyone working with CloudStack code and
docs.

Best, 

Joe
-- 
"Another flaw in the human character is that everybody wants 
to build and nobody wants to do maintenance." ~ Kurt Vonnegut

Joe 'Zonker' Brockmeier <jz...@zonker.net>

Re: Creating an Apache cloudstack docs repo: please discuss

[Jessica Tomechak <je...@gmail.com>]

>
> -----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Monday, July 02, 2012 6:12 AM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: Creating an Apache cloudstack docs repo: please discuss
>
> On Sun, Jul 1, 2012 at 11:23 PM, Joe Brockmeier <jz...@zonker.net> wrote:
> > On Sat, Jun 30, 2012 at 04:27:30PM +0200, Mohammad Nour El-Din wrote:
> >> I would go with approch of having the docs in the same repo under say
> >> /docs as David mentioned
> >
> > +1
> >
> > Some projects may do this differently, but it's usually the norm to
> > keep documentation with the rest of the code.
> >
> >> Take into account that having more than one repo will need more work
> >> and infra management
> >
> > Not to mention a headache for anyone working with CloudStack code and
> > docs.
> >
> > Best,
> >
> > Joe
> > --
>
>
> So lets turn this around - Jessica, et al, are there benefits that you
> think will accrue to you from having a separate repo, and what are they?
>
> --David
>

A quick search reveals some discussions of the pros and cons, like:
https://groups.google.com/forum/?fromgroups#!topic/silverstripe-documentation/R1k7uS488Xg

I don't have a strong opinion, actually. I'm perfectly happy to have a
discussion and come to whatever decision seems right.

In favor of keeping docs in the same repo with code: it's very helpful to
be able to submit doc updates along with code updates in a single patch.
Also, using a single repo makes it easier to find the docs -- and remember
to maintain them.

The "pros" for a separate repo: It can be argued that we don't always need
to version the docs for each release -- we can reduce the number of doc
versions we have to track and maintain. Therefore, branching and tagging
for releases can be a distraction from the docs point of view.

Also, weighing down the repo with large graphics seems like a possible
issue. When I clone a repo, I wouldn't like to pull down something that's
only 5% code by volume.

Jessica T.
CloudStack Tech Pubs

Re: Creating an Apache cloudstack docs repo: please discuss

[David Nalley <da...@gnsa.us>]

On Sun, Jul 1, 2012 at 11:23 PM, Joe Brockmeier <jz...@zonker.net> wrote:
> On Sat, Jun 30, 2012 at 04:27:30PM +0200, Mohammad Nour El-Din wrote:
>> I would go with approch of having the docs in the same repo under say /docs
>> as David mentioned
>
> +1
>
> Some projects may do this differently, but it's usually the norm to keep
> documentation with the rest of the code.
>
>> Take into account that having more than one repo will need more work and
>> infra management
>
> Not to mention a headache for anyone working with CloudStack code and
> docs.
>
> Best,
>
> Joe
> --


So lets turn this around - Jessica, et al, are there benefits that you
think will accrue to you from having a separate repo, and what are
they?

--David