Open Stack

Hi,

<snip>
________________________________________
From: Steve Gordon [sgordon at redhat.com]
Sent: Thursday, July 11, 2013 7:39 PM
To: Shaun McCance
Cc: openstack-docs at lists.openstack.org
Subject: Re: [Openstack-docs] Linking to external install guides

----- 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

_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

</snip>

I am one of the guy from the documentation team working on the basic install guide. But i found things getting changed after Essex.

1. We had other distros supporting Openstack as well.
2. Many new projects got added <quantum/nuetron> which requires additional hardware to get things in place.

Now what my suggestion is/was :--

1. Identify One person who is a distribution expert & can work with us & help us in getting the basic install setup in place. I think we already have one from each distribution for same.

2. Create a basic install guide which will cover every component (YES  Swift & Cinder included) per distribution.

3. Distribution like RedHat has extended documentation resource am sure Suse/Ubuntu/Debian would be having same. To get more fine grind distro level configuration accomplishment point them to distributed distro. They have their own best way or suggested way of deployment packstack/Juju & one who wants to explore those should visit respective site.

We should focus on adding/documenting new features which are incorporated with every release in every component i.e fiber channel/scheduler & many goodness coming in new release. This will save a lot of time & we can spend it in adding the features in doc rather than running after distro based install steps.

Also Ubuntu has cloud archive from long time which keeps testing packages[1], so i personally don`t think we could/should/would have difficulty is publishing basic install doc same day of our release. We have done this before as well. :)

What do you people think?

Thanks!!

Atul Jha
(@koolhead17)

[1] https://wiki.ubuntu.com/ServerTeam/CloudArchive
http://www.csscorp.com/common/email-disclaimer.php