cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jessica Tomechak <jessica.tomec...@gmail.com>
Subject Re: Creating an Apache cloudstack docs repo: please discuss
Date Mon, 02 Jul 2012 21:49:54 GMT
>
> -----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 <jzb@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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message