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: Breaking docs out
Date Tue, 20 Aug 2013 21:35:47 GMT
Regarding David's point about the Install, Admin, and Dev guides having a
lot of similar content, making it hard to break their source files apart:
it's possible most of the similar content is in the "Infrastructure
Concepts" section, where we explain "what is a zone, what is a pod," etc.

I'm not sure how often we duplicate any other sections in >1 guide.
However, I like having the option to easily do so. I don't mind breaking
some clearly stand-alone docs into separate repos to make lives easier. But
I'm not sure I'd be as happy separating all the guides.

If I understand this correctly, we'd have to check one doc section into
three repos to make it appear in three guides, then remember to check all
updates into all three repos in perpetuity. Please let me know if I'm in
error on that.

Curious how this will be resolved,
Jessica T.


On Tue, Aug 20, 2013 at 1:43 PM, Animesh Chaturvedi <
animesh.chaturvedi@citrix.com> wrote:

> The docs for 4.2 are not settled yet and may take another couple of days.
> David are you considering the change for 4.2?
> > -----Original Message-----
> > From: Daan Hoogland [mailto:daan.hoogland@gmail.com]
> > Sent: Wednesday, August 07, 2013 12:11 AM
> > To: dev
> > Subject: Re: Breaking docs out
> >
> > ok,
> >
> > +0 then, I'm off for a coffee.
> >
> > On Tue, Aug 6, 2013 at 10:21 PM, Jessica Tomechak
> > <Jessica.Tomechak@citrix.com> wrote:
> > > I'm +0 on it. Don't really mind either way.
> > >
> > > Jessica T.
> > > ________________________________________
> > > From: Radhika Puthiyetath [radhika.puthiyetath@citrix.com]
> > > Sent: Monday, August 05, 2013 9:25 PM
> > > To: dev@cloudstack.apache.org
> > > Subject: RE: Breaking docs out
> > >
> > > Make perfect sense.
> > > + 1
> > >
> > > -Radhika
> > >
> > > -----Original Message-----
> > > From: David Nalley [mailto:david@gnsa.us]
> > > Sent: Tuesday, August 06, 2013 3:13 AM
> > > To: dev@cloudstack.apache.org
> > > Subject: Breaking docs out
> > >
> > > Hi folks:
> > >
> > > I'd like to propose breaking out a nuymber of our documents into their
> > own repos.
> > >
> > > My thinking is that specifically; the release notes, midonet, and
> > niciranvp documentation shares very little with the rest of the
> > documentation, and should be broken out akin to how the QIG is currently
> > broken out.
> > >
> > > The particular problem I am trying to solve is to deal with
> > publishing. For instance, even though the release notes are contained in
> > just a few xml documents, it copies content from every single xml file
> > in thd directory - over 400 - and it also copies those up to the
> > website.
> > >
> > > Splitting things up also allows us to prioritize l10n. Right now, we
> > just dump 400 xml files worth of content into transifex and people
> > translate away - they can't put a priority on release notes, or de-
> > emphasize more esoteric documentation like Nicira or Midonet.
> > >
> > > Eventually I'd like to break out each of the individual guides into
> > their own document - separate from the other. Right now they carry a ton
> > of similar content so that isn't very practical; but it's what I am
> > thinking, perhaps for 4.4 or 4.5.
> > >
> > > In the meantime, I'd like to make this change as soon as we think we
> > have documentation pretty close to done for 4.2 to minimize the
> > disruptive effects.
> > >
> > > Thoughts, comments, flames?
> > >
> > > --David
>

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