<div dir="ltr">With those thoughts in mind, here are my $0.02:<div><br></div><div>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.</div>
<div><br></div><div>In all cases, I always have them focus on editing the various configuration files manually. This is for a few reasons:</div><div><br></div><div>1. It works across all distros.</div><div>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.</div>
<div>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).</div>
<div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>Joe</div>
</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Feb 21, 2014 at 8:55 PM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote"><div class="">On Thu, Feb 20, 2014 at 1:03 PM, phil hopkins <span dir="ltr"><<a href="mailto:phil.hopkins@rackspace.com" target="_blank">phil.hopkins@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000">
I believe we are missing a key point, which is what is the purpose
of the install guide? If it is just to help folks quickly get
OpenStack or are we also trying to teach them about OpenStack as
they install it to help them become proficient and quickly as
possible? If we decide on the purpose of the book then many of these
other detail will resolve themselves.<span><font color="#888888"><br>
<br></font></span></div></blockquote><div><br></div></div><div>Here's my current line of thought:</div><div><br></div><div>- The "official" install guide should offer instruction to anyone wanting to set up OpenStack in a non-DevStack environment with a single happy path, even if it's simple.</div>
<div><br></div><div>- The "official" install guide should offer a few different ideas for installers who want to know what setups still give them "OpenStack" such as:</div><div> ---Compute with nova-network</div>
<div> ---Compute with neutron</div><div> ---Object Storage, Identity only <br></div><div><br></div><div>- The "official" install guide should provide enough information for someone to learn from to then create or use a more repeatable method of install/deploy such as Chef, Juju, or Puppet and be able to read or write those recipes with a good understanding of why OpenStack services go together the way they do.</div>
<div><br></div><div>With these goals in mind is it advantageous to:</div><div>- unify on one AMQP broker?</div><div>- analyze the maintenance savings by doing a trial non-openstack-config rewrite on one chapter?</div><div>
<br></div><div><div>Hope this is helpful -- thanks all for the questions and discussion. </div></div><span class="HOEnZb"><font color="#888888"><div><br></div><div>Anne</div></font></span><div class=""><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"><span><font color="#888888">
Phil</font></span><div><div><br>
<br>
<div>On 02/20/2014 12:53 PM, Joe Topjian
wrote:<br>
</div>
</div></div><blockquote type="cite"><div><div>
<div dir="ltr">Hi Steve,
<div><br>
<div class="gmail_extra">
<div class="gmail_quote">
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">What's
the upside of using this function over crudini if all
the platforms we're building the guide for package the
latter?</blockquote>
<div><br>
</div>
<div>Admittedly, the only upside is that crudini is not
guaranteed to be easily available on all distributions.
For Ubuntu, it's only available in Ubuntu 14.04, for
example. </div>
<div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"> I
think awkward is a bit of an understatement here and
suggesting that this isn't a "special tool" that also
needs to be installed/enabled is perhaps stretching
things - in either case it's something the user is going
to have to handle in the prerequisites and ensure they
repeat on each node (and make sure it takes effect for
each session for iniset).<br>
</blockquote>
<div><br>
</div>
<div>Fair, but it can be simplified by just doing a "wget"
or something similar.</div>
<div><br>
</div>
<div>The upside of iniset is that it's portable and is
known to work on all distributions. As soon as a
distribution lacks support, or drops support, for
crudini, the installation instructions are now broke.</div>
<div><br>
</div>
<div>Joe</div>
</div>
</div>
</div>
</div>
<br>
<fieldset></fieldset>
<br>
</div></div><div><pre>_______________________________________________
Openstack-docs mailing list
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a>
</pre>
</div></blockquote>
<br>
</div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br></blockquote></div></div></div></div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br></div>