Open Stack

----- Original Message -----
> From: "Shaun McCance" <shaunm at gnome.org>
> To: "Tom Fifield" <tom at openstack.org>
> Cc: openstack-docs at lists.openstack.org
> Sent: Thursday, July 11, 2013 9:16:28 AM
> Subject: Re: [Openstack-docs] Linking to external install guides
> 
> On Wed, 2013-07-10 at 15:46 +1000, Tom Fifield wrote:
> > On 10/07/13 15:40, Andreas Jaeger wrote:
> > > On 07/10/2013 02:34 AM, Tom Fifield wrote:
> > >> I'll take a bullish line, which may not necessarily be achievable:
> > >>
> > >> """
> > >> On the day that the press release for Havana is sent out, we need -by
> > >> hook or by crook!- to have installation instructions for RHEL and
> > >> Ubuntu, and ideally SUSE and Debian too.
> > >> """
> > >
> > > What kind of instructions are you looking at? The "Basic installation"
> > > ones, the current "installation guides" - or both?
> > >
> > > Andreas
> > 
> > Thanks for the reply!!
> > 
> > I think the answer is: "something" ;)
> > 
> > My personal impression is:
> > * the basic install guide is too basic right now
> > * the install guides are too heavy
> > 
> > so ideally what I would be looking for as a deployer is something that
> > gives me a basic installation, with a bit of explanation on why the
> > steps are being taken.
> > 
> > 
> > However, I believe Shaun McCance is taking a very serious look at the
> > installation guides right now and should be able to provide an
> > authoritative answer.
> 
> That's more or less my impression. I don't like that there's two guides.
> It's asking readers to make an upfront decision that they're probably
> not in a position to make. My preference would be a single install guide
> that's structured such that you get a basic, working install within the
> first few chapters, and can choose your own adventure after that.

Right, I agree that the fact that there are two guides is a problem both for readers and for the writers attempting to keep them up to date. I think that there is some debate around what a "basic, working install" looks like though and in part that's what led to there being two guides in the first place. From my point of view a basic working install means you can run up an instance and it will have network connectivity, but that statement still leaves questions like:

- Do you omit block storage (Cinder) setup because strictly speaking you don't need volumes to run a VM?
- Do you omit object storage (Swift) setup because it's not strictly needed or do you use it as the backend for image storage (Glance)?

Another key point raised in the previous review of the basic-install guide was that while it gets the user up and running in a more streamlined fashion it can leave them in a bit of a bind when it comes to expanding [1]. So I think on top of my statement that a basic working install means "you can run up an instance and it will have network connectivity" there probably needs to be some consideration of ensuring the initial deployment allows for easy expansion without having to go back and rework the original endpoints etc. when it comes to the choose your own adventure part. 

> The current full install guide feels random, like pieces were added to
> it over time without a lot of thought to the overall narrative. The
> basic install guide is nice for what it is. I'd just prefer it were
> incorporated into a larger work.
> 
> And I believe very strongly that your docs should be ready on release
> day. They're part of your fanfare, and should be linked to from your
> marketing materials.

I am +1 on this but am concerned about expending too much effort on "install from source" instructions if most users are ultimately going to install from packages (even if there is a 1-2 day lag for packaging, which is the advice I am getting on rdo-list). My perhaps unrealistic suggestion is that we conditionalize such that we can have "source", "debian;ubuntu", and "rhel;fedora;centos" paths through a single installation guide (I provide these as examples, obviously where other distros such as SuSE differ and need an additional path they would also be more than welcome). The package-based options would be contingent on someone being willing to maintain them though - obviously I would be looking to be heavily involved from an RPM side. The "from source" path would be the only one that would be considered release blocking/must have though because ultimately it's the only one likely to be there on 0-day of the release. Thoughts?

Thanks,

Steve

[1] http://lists.openstack.org/pipermail/openstack-docs/2013-April/001510.html