> > -----Original Message----- > From: David Nalley [mailto:[email protected]] > Sent: Monday, July 02, 2012 6:12 AM > To: [email protected] > Subject: Re: Creating an Apache cloudstack docs repo: please discuss > > On Sun, Jul 1, 2012 at 11:23 PM, Joe Brockmeier <[email protected]> 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
