Open Stack

----- Original Message ----- 

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

Per the earlier discussion it seems to me crudini works fine on 3 out of 4 distributions we currently build for and can be added to the 4th (and will be included in it come next release).

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

I see no difference in the pattern here regardless of whether a helper is used or not? The helper doesn't hide the configuration file location or the settings being applied, they are both right there on the command line - it's just much easier to copy paste and minimizes the amount of prose required to cover edge cases like the configuration group not being there yet.

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

What unique configuration options are not supported by the crudini helper, it's just an ini parser?

All of the above said I've really given up on the configuration editor argument, but it seems like a lot of these points could have been argued in earnest both ways. I don't really see a clear win on either side of the fence.

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

I share Thomas' concern about moving this stuff to appendices, having distribution targeted guides works and flows well as is. I don't see value in hiding it in appendices to remove only what I expect to be a small subset of conditionals. If you want to remove it, remove it, lets not push it to an appendix and pretend that's a win for readers versus having it inline or not having it at all though.

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

I think regardless of intent we need to be honest and recognize that as an inevitable end result of such a decision. What is the impact of the current queuing documentation to the end user that we're trying to avoid, given that the guides have already been conditionalized for it - as an end user I currently don't see both Qpid and Rabbit MQ in the same guide that I'm ultimately reading?

I don't think anyone here at RH expects others to write the Qpid documentation for us, but we've been pretty active in contributing to it and making corrections where necessary up to this point, obviously I'm also heavily involved in reviews and try to catch any issues there too. Is the concern that we're not keeping up?

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

If it's just the AMQP service, how much effort is actually being focused on it right now instead of those other things? It seems to me unless another example presents itself we're fixing a problem that doesn't yet exist? As an example is the Neutron documentation suffering because we have conditionalized AMQP setup, or because we're all having a lot of difficulty getting neutron itself working in a reproducible way ;) (I know Matt has been doing a lot of great work in this area, but it's a tough slog for anyone on the team).

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

The options required to set up each service for message queues are minimal and consistent, I think it's a stretch to say we're expecting authors to be experts in a huge array of components here. You also only really have to do it when we add a new project to the guide. 

> 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 kind of allude to it above, but the reason we're able to have a conditionalized guide for Ubuntu, Debian, SUSE, and RHEL in the first place is that authors from the various distributors have stepped up and done the work to make it so. We've also been pretty active in helping each other out when it comes to reviews, if I notice a patch where I think there's a discrepancy for SUSE or Debian that's not noted then I'll highlight it to Andreas or Thomas and vice versa (admittedly I'm not sure we have a point person for Ubuntu, instead we all just pitch in - including myself). 

I do think the conditionals might have some impact on discouraging drive by commits, but I think that's arguing the toss somewhat when the elephant in the room is that we're using DocBook which I suspect has a much bigger impact on such contributions. Whether that is a good or bad thing is something I know we've passionately debated in the past :).

Another key concern from my point of view is that we're nearing the point of the release where we finally start to get a clear picture of what's actually made the release, and it seems like we're  contemplating open heart surgery on the installation guide again. I would prefer to see more incremental change now, discussion at summit, and then if it's decided that major change is indeed necessary (again) to do that work *early* in the cycle, not be having the discussion again at *-3. 

Thanks,

Steve