Open Stack

On Wed, Feb 26, 2014 at 1:05 PM, Andreas Jaeger <aj at suse.com> wrote:

> On 02/26/2014 06:58 PM, Joe Topjian wrote:
> > With those thoughts in mind, here are my $0.02:
> >
> > I frequently work with system administrators new to OpenStack and
> > planning to deploy once they learned how to use it. I've worked with
> > Ubuntu, Red Hat, and Debian users. I don't try to convince them to pick
> > one distro or the other -- that's their decision.
> >
> > In all cases, I always have them focus on editing the various
> > configuration files manually. This is for a few reasons:
> >
> > 1. It works across all distros.
> > 2. It invokes more of a rote learning mindset, which I find a benefit
> > when learning something new. It works, too. By the time the user has
> > reached installing the Cinder service, they already know the 3-step
> > pattern (install packages, edit config file, restart service), as well
> > as have a general idea of where the config file is located and what
> > common settings are applied.
> > 3. Even when they try to use a "helper" tool such as openstack-config or
> > the debconf tool, they always have to go back to manually edit the
> > configuration file for some reason or another (typo, option unique to
> > their environment, etc).
> >
> > To create a solid foundation for learning OpenStack, I feel the user
> > must know their way around the configuration files, so I think the
> > installation instructions should be as distro-agnostic and fundamental
> > as possible.  As stated in Anne's original email, appendixes can be
> > created for the distro-specific tools (and even the iniset devstack
> > function). It won't be possible to get rid of all conditional markup, as
> > each distro has a different way to install packages, restart services,
> etc.
> >
> > Regarding the supplemental components of the install (RabbitMQ, MySQL,
> > etc), I think a standard set of components should be used if they work
> > across all distros. I understand that this might come across as
> > endorsing the component as the "official" choice of an OpenStack
> > installation, but that's not the intent. Instead, the intent is to use a
> > standard set of working components in order to focus on the OpenStack
> > installation itself. More time can be devoted to documenting the various
> > OpenStack installation types (nova-network, neutron, object storage
> > only, etc). Short of the AMQP service, I can't think of any other
> > service that differs from distro to distro, but I think the idea is
> > important.
> >
> > Additionally, once a standard set of components is used, supplemental
> > documentation (appendixes?) can be written by experts of different
> > components. This allows install guide authors to focus on one set and
> > not have to be a "jack of all trades" to support all possible components
> > while at the same time tapping the community for experts in other areas.
> >
> > So that's my opinion. I realize it holds little weight as I don't
> > contribute as much to docs as I did a few months ago. But I do work
> > hands-on with OpenStack every day and frequently meet with people to
> > help them get started. These views are a result of my experience.
>
>
I think Joe's experience is similar to others I've talked to, especially
trainers. So I think this additive approach is great.


>
> I have nothing against replacing openstack-config with general
> instructions for editing - and placing openstack-config or crudini in an
> appendix.
>
> We can also write the install instructions in a more generic way, so say
> for example:
> On Ubuntu, install the package "cinder".
> On Fedora, openSUSE ... install the package "openstack-cinder".
>
> And have a distro specific appendix where it's documented that for
> installing packages you run on Fedora "yum install $package", on
> openSUSE "zypper install $package" ...
> The disadvantage is that you cannot copy & paste the complete command-line.
>
>
I think we have to keep copy and paste -- based on what I've seen over the
years.


> Both should reduce some of the conditionals we currently have. I agree
> with you that there are differences between distributions and their
> packages and we should account for these.
>
> I really suggest that somebody writes down what exactly is proposed
> (incl. instruction on what to change) and perhaps converts a section or
> two to see how it looks.
>

Yep, that's what I've asked Phil and Matt and crew to do (convert the
neutron chapters for an example). We can continue shaping in the review
itself then.

Sorry for any confusion but I do appreciate the hard work going on here!
Anne


>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140226/124c0192/attachment-0001.html>